Orishare
Api

List customers (newest first)

GET
/customers

Authorization

bearer
AuthorizationBearer <token>

Secret key (osk_…), publishable key (opk_…) or personal access token (opat_…).

In: header

Query Parameters

limit?integer
Range1 <= value <= 200
Default50
cursor?string
Lengthlength <= 2048
external_id?string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customers"
{  "data": [    {      "id": "string",      "external_id": "string",      "attributes": {        "property1": null,        "property2": null      },      "version": 0,      "deleted_at": "string",      "created_at": "string",      "updated_at": "string"    }  ],  "next_cursor": "string",  "has_more": true}

Create or update a customer by external id (201 created, 200 updated)

POST
/customers

Authorization

bearer
AuthorizationBearer <token>

Secret key (osk_…), publishable key (opk_…) or personal access token (opat_…).

In: header

Header Parameters

Idempotency-Key?string

Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/customers" \  -H "Content-Type: application/json" \  -d '{    "external_id": "cust_123",    "attributes": {      "plan": "premium",      "country": "US"    }  }'
{  "id": "string",  "external_id": "string",  "attributes": {    "property1": null,    "property2": null  },  "version": 0,  "deleted_at": "string",  "created_at": "string",  "updated_at": "string"}

One customer by id or external id

GET
/customers/{id}

Authorization

bearer
AuthorizationBearer <token>

Secret key (osk_…), publishable key (opk_…) or personal access token (opat_…).

In: header

Path Parameters

id*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customers/string"
{  "id": "string",  "external_id": "string",  "attributes": {    "property1": null,    "property2": null  },  "version": 0,  "deleted_at": "string",  "created_at": "string",  "updated_at": "string"}

Merge-patch attributes (null removes a key)

PATCH
/customers/{id}

Authorization

bearer
AuthorizationBearer <token>

Secret key (osk_…), publishable key (opk_…) or personal access token (opat_…).

In: header

Path Parameters

id*string
Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/customers/string" \  -H "Content-Type: application/json" \  -d '{    "attributes": {      "property1": null,      "property2": null    }  }'
{  "id": "string",  "external_id": "string",  "attributes": {    "property1": null,    "property2": null  },  "version": 0,  "deleted_at": "string",  "created_at": "string",  "updated_at": "string"}

Delete: redact attributes and events, remove aliases, keep ledger history

DELETE
/customers/{id}

Authorization

bearer
AuthorizationBearer <token>

Secret key (osk_…), publishable key (opk_…) or personal access token (opat_…).

In: header

Path Parameters

id*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/customers/string"
Empty

Data export: profile, aliases, events in the hot window, ledger entries, issuances, tiers and challenge progress as one document

GET
/customers/{id}/export

Authorization

bearer
AuthorizationBearer <token>

Secret key (osk_…), publishable key (opk_…) or personal access token (opat_…).

In: header

Path Parameters

id*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customers/string/export"
{  "exported_at": "string",  "customer": {    "id": "string",    "external_id": "string",    "attributes": {      "property1": null,      "property2": null    },    "version": 0,    "deleted_at": "string",    "created_at": "string",    "updated_at": "string"  },  "aliases": [    {      "alias": "string",      "created_at": "string"    }  ],  "events": [    {      "id": "string",      "name": "string",      "occurred_at": "string",      "received_at": "string",      "properties": null    }  ],  "events_since": "string",  "ledger_entries": [    {      "id": "string",      "currency": "string",      "type": "string",      "status": "string",      "amount": 0,      "remaining": 0,      "expires_at": "string",      "reason": "string",      "source_type": "string",      "created_at": "string"    }  ],  "reward_issuances": [    {      "id": "string",      "reward": "string",      "status": "string",      "expires_at": "string",      "redeemed_at": "string",      "cancelled_at": "string",      "created_at": "string"    }  ],  "tiers": [    {      "program": "string",      "level": "string",      "since": "string"    }  ],  "challenge_progress": [    {      "challenge": "string",      "period_key": "string",      "count": 0,      "completed_at": "string"    }  ]}

Balances, tiers, segments, counters, challenge progress, issuances and aliases

GET
/customers/{id}/state

Authorization

bearer
AuthorizationBearer <token>

Secret key (osk_…), publishable key (opk_…) or personal access token (opat_…).

In: header

Path Parameters

id*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customers/string/state"
{  "customer": {    "id": "string",    "external_id": "string",    "attributes": {      "property1": null,      "property2": null    },    "version": 0,    "deleted_at": "string",    "created_at": "string",    "updated_at": "string"  },  "balances": [    {      "currency": "string",      "available": 0,      "pending": 0,      "lifetime_earned": 0    }  ],  "tiers": [    {      "program_id": "string",      "level": "string",      "since": "string"    }  ],  "segments": [    "string"  ],  "counters": {    "property1": 0,    "property2": 0  },  "challenges": [    {      "challenge_id": "string",      "period_key": "string",      "count": 0,      "status": "string"    }  ],  "issuances": [    {      "id": "string",      "reward_id": "string",      "status": "string",      "expires_at": "string"    }  ],  "aliases": [    {      "alias": "string",      "kind": "anonymous",      "customer_id": "string",      "created_at": "string"    }  ]}
POST
/customers/{id}/aliases

Authorization

bearer
AuthorizationBearer <token>

Secret key (osk_…), publishable key (opk_…) or personal access token (opat_…).

In: header

Path Parameters

id*string
Length1 <= length

Header Parameters

Idempotency-Key?string

Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/customers/string/aliases" \  -H "Content-Type: application/json" \  -d '{    "alias": "anon_9f3a"  }'
{  "alias": {    "alias": "string",    "kind": "anonymous",    "customer_id": "string",    "created_at": "string"  },  "merged_from": "string"}

Mint the token a browser must present to send events as this customer

POST
/customers/{id}/client_token

Authorization

bearer
AuthorizationBearer <token>

Secret key (osk_…), publishable key (opk_…) or personal access token (opat_…).

In: header

Path Parameters

id*string
Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/customers/string/client_token"
{  "customer_id": "string",  "external_id": "string",  "customer_token": "string"}

Declared customer attributes with types and PII flags

GET
/attribute_definitions

Authorization

bearer
AuthorizationBearer <token>

Secret key (osk_…), publishable key (opk_…) or personal access token (opat_…).

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/attribute_definitions"
{  "data": [    {      "id": "string",      "key": "string",      "type": "string",      "description": "string",      "pii": true,      "created_at": "string",      "updated_at": "string"    }  ],  "next_cursor": "string",  "has_more": true}

Declare or update an attribute definition by key

POST
/attribute_definitions

Authorization

bearer
AuthorizationBearer <token>

Secret key (osk_…), publishable key (opk_…) or personal access token (opat_…).

In: header

Header Parameters

Idempotency-Key?string

Required by the API on this route (400 idempotency_key_required without it); the official clients generate a UUID when you omit it.

Length1 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/attribute_definitions" \  -H "Content-Type: application/json" \  -d '{    "key": "string",    "type": "string"  }'
{  "id": "string",  "key": "string",  "type": "string",  "description": "string",  "pii": true,  "created_at": "string",  "updated_at": "string"}

Counters

Historical counter definitions and backfills.

Events

Ingestion (202 async, 200 sync), event definitions, retries.