Usage of Metadata on Endusers

Overview

This guide describes how to use the metadata field on Endusers in the Kobble API. It is intended for clients integrating with Kobble who need to attach custom context to enduser records.

Summary: For endusers, metadata is a free JSON object with no validation. You can attach any structured customer context (e.g. CRM ids, KYC tags, segmentation) that your client needs. Kobble stores and returns it as-is; it is not used for business logic or validation.

What is enduser metadata?

Type: A JSON object.

Validation: None. The API accepts any valid JSON object.

Purpose: To store client-defined, structured context about the enduser (the person or company that holds a wallet/card).

Use it for anything that helps your systems identify, segment, or manage the enduser.
for example:

Use case	Example keys / structure
CRM linkage	`crm_id`, `salesforce_id`, `hubspot_contact_id`
KYC / compliance	`kyc_status`, `kyc_tier`, `aml_checked`
Segmentation	`segment`, `cohort`, `risk_band`, `product_line`
Internal refs	`policy_no`, `account_ref`, `notes`

You define the keys and values; Kobble does not interpret or validate them.

How to send metadata

On create (person)

When creating an enduser of type person with POST /api/endusers, include an optional metadata object in the body:

{
  "person": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "phone_number": "+61400000000"
  },
  "metadata": {
    "crm_id": "CRM-12345",
    "kyc_tier": "verified",
    "segment": "premium"
  }
}

On create (company)

When creating an enduser of type company, you can pass the same optional metadata object:

{
  "company": {
    "name": "Acme Pty Ltd"
  },
  "metadata": {
    "crm_id": "CRM-67890",
    "kyc_status": "approved",
    "notes": "VIP-company"
  }
}

Omitting metadata

metadata is optional. If you omit it, Kobble stores an empty object {}.

You can send metadata: {} explicitly if you prefer.

Response and storage

Create: The created enduser in the response includes the same metadata object you sent.

List / Get: GET /api/endusers and GET /api/endusers/:id both return the stored metadata for each enduser.

Kobble does not modify or validate the contents; it is persisted and returned as provided.

Best practices (for clients)

Keep it structured: Use consistent key names and value types (e.g. always string for ids) so your own systems can rely on them.

Avoid PII in metadata if not required: Prefer opaque ids (e.g. CRM id) over raw PII unless you need it for operations.

Document your schema internally: Since there is no server-side validation, documenting your chosen keys and formats helps avoid mistakes and helps support.

Usage of Metadata on Endusers

Overview#

What is enduser metadata?#

How to send metadata#

On create (person)#

On create (company)#

Omitting metadata#

Response and storage#

Best practices (for clients)#