Customers | Orishare docs

List customers (newest first)

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Query Parameters

limit?integer

Range1 <= value <= 200

Default50

cursor?string

Lengthlength <= 2048

external_id?string

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length

X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/customers"

{  "data": [    {      "id": "string",      "external_id": "string",      "timezone": "string",      "attributes": {        "property1": null,        "property2": null      },      "version": 0,      "deleted_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string",  "has_more": true}

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

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Header Parameters

Idempotency-Key*string

Required. Official clients generate a UUID when omitted by the caller.

Length1 <= length <= 255

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length

X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

external_id*string

Length1 <= length <= 200

attributes?

anonymous_id?string

Length1 <= length <= 200

timezone?|null

Response Body

`application/json`

curl -X POST "https://example.com/customers" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "external_id": "reader_42",    "attributes": {}  }'

{  "id": "string",  "external_id": "string",  "timezone": "string",  "attributes": {    "property1": null,    "property2": null  },  "version": 0,  "deleted_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

One customer by id or external id

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

Length1 <= length

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length

X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

`application/json`

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

{  "id": "string",  "external_id": "string",  "timezone": "string",  "attributes": {    "property1": null,    "property2": null  },  "version": 0,  "deleted_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Merge-patch attributes (null removes a key)

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

Length1 <= length

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length

X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

If-Match?string

Optional legacy revision. Missing or malformed values follow the existing route parser.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

attributes?

timezone?|null

Response Body

`application/json`

curl -X PATCH "https://example.com/customers/string" \  -H "Content-Type: application/json" \  -d '{    "attributes": {      "favorite_genre": "history"    }  }'

{  "id": "string",  "external_id": "string",  "timezone": "string",  "attributes": {    "property1": null,    "property2": null  },  "version": 0,  "deleted_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

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

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

Length1 <= length

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length

X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

`application/json`

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

Empty

Complete data export: profile plus the first page of every history section (events, ledger, programs, streaks, badges, quests, levels, leaderboards, referrals, commerce, identity, merges); continue a section on /customers/{id}/export/{section}

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

Length1 <= length

Query Parameters

limit?integer

Range1 <= value <= 1000

Default200

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length

X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/customers/string/export"

{  "export_version": -9007199254740991,  "generated_at": "2019-08-24T14:15:22Z",  "section_names": [    "aliases"  ],  "page_limit": -9007199254740991,  "events_archive": "included",  "sections": {    "property1": {      "data": [        {          "property1": null,          "property2": null        }      ],      "next_cursor": "string"    },    "property2": {      "data": [        {          "property1": null,          "property2": null        }      ],      "next_cursor": "string"    }  },  "exported_at": "2019-08-24T14:15:22Z",  "customer": {    "id": "string",    "external_id": "string",    "timezone": "string",    "attributes": {      "property1": null,      "property2": null    },    "version": 0,    "deleted_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  },  "member_profiles": [    {      "id": "string",      "external_id": "string",      "timezone": "string",      "attributes": {        "property1": null,        "property2": null      },      "version": 0,      "deleted_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "aliases": [    {      "alias": "string",      "customer_id": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "events": [    {      "id": "string",      "customer_id": "string",      "name": "string",      "occurred_at": "2019-08-24T14:15:22Z",      "received_at": "2019-08-24T14:15:22Z",      "properties": null    }  ],  "events_since": "2019-08-24T14:15:22Z",  "ledger_entries": [    {      "id": "string",      "customer_id": "string",      "currency": "string",      "type": "string",      "status": "string",      "amount": 0,      "remaining": 0,      "expires_at": "2019-08-24T14:15:22Z",      "reason": "string",      "source_type": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "economy_awards": [    {      "ledger_entry_id": "string",      "customer_id": "string",      "currency": "string",      "amount": 0,      "source_type": "string",      "source_id": "string",      "trust_level": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "reward_issuances": [    {      "id": "string",      "customer_id": "string",      "reward": "string",      "status": "string",      "expires_at": "2019-08-24T14:15:22Z",      "redeemed_at": "2019-08-24T14:15:22Z",      "cancelled_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "tiers": [    {      "customer_id": "string",      "program": "string",      "level": "string",      "since": "2019-08-24T14:15:22Z"    }  ],  "challenge_progress": [    {      "customer_id": "string",      "challenge": "string",      "period_key": "string",      "count": 0,      "completed_at": "2019-08-24T14:15:22Z"    }  ],  "dates": [    {      "customer_id": "string",      "key": "string",      "month": -9007199254740991,      "day": -9007199254740991,      "year": -9007199254740991,      "set_by": "customer",      "set_at": "2019-08-24T14:15:22Z"    }  ]}

One page of one customer export section; follow next_cursor until it is null to read the section completely

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

Length1 <= length

section*string

Value in

"aliases"
"auth_states"
"identity_links"
"session_families"
"sessions"
"merges"
"ownership_links"
"segment_memberships"
"experiment_assignments"
"events"
"event_receipts"
"rule_executions"
"business_facts"
"balances"
"ledger_entries"
"reward_issuances"
"tiers"
"challenge_enrollments"
"challenge_progress"
"program_participations"
"program_transitions"
"program_contributions"
"program_award_links"
"mechanic_facts"
"streak_periods"
"streak_milestones"
"streak_inventory"
"streak_freeze_lots"
"streak_freeze_entries"
"badge_grants"
"badge_revocations"
"achievement_progress"
"achievement_entries"
"achievement_distinct_members"
"quest_runs"
"quest_step_states"
"quest_entries"
"quest_claims"
"quest_distinct_members"
"level_runs"
"level_attainments"
"leaderboard_entries"
"leaderboard_profiles"
"leaderboard_scores"
"leaderboard_contributions"
"leaderboard_prize_settlements"
"leaderboard_prize_allocations"
"leaderboard_prize_effects"
"referral_codes"
"referral_attributions"
"referral_conversions"
"referral_settlements"
"referral_beneficiaries"
"referral_pending_holds"
"referral_reward_reservations"
"redemption_quotes"
"reward_redemptions"
"fulfillments"
"reward_coupon_entitlements"
"reward_code_allocations"
"reward_commerce_facts"
"reward_commerce_rule_effects"
"league_memberships"
"league_entries"
"league_score_events"
"social_profile"
"notification_contact"
"notification_preferences"
"notification_devices"
"notification_messages"
"inventory_holdings"
"inventory_entries"
"energy_states"
"energy_entries"
"boost_activations"
"loot_draws"
"economy_award_provenance"
"battle_pass_premiums"
"battle_pass_claims"
"match_result_players"
"streak_commands"
"customer_dates"
"store_credit_applications"
"connector_orders"
"import_rows"
"klaviyo_sync"
"points_transfers"
"friend_codes"
"friendships"
"social_blocks"
"social_reactions"
"friend_quests"
"friend_quest_contributions"
"friend_streaks"
"friend_streak_days"
"friend_streak_awards"
"teams_owned"
"team_memberships"
"team_quest_contributions"
"team_quest_rewards"

Query Parameters

limit?integer

Range1 <= value <= 1000

Default200

cursor?string

Lengthlength <= 2048

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length

X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/customers/string/export/aliases"

{  "section": "aliases",  "customer_id": "string",  "events_archive": "included",  "data": [    {      "property1": null,      "property2": null    }  ],  "next_cursor": "string",  "has_more": true}

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

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

Length1 <= length

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length

X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/customers/string/state"

{  "customer": {    "id": "string",    "external_id": "string",    "timezone": "string",    "attributes": {      "property1": null,      "property2": null    },    "version": 0,    "deleted_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  },  "balances": [    {      "currency": "string",      "available": 0,      "pending": 0,      "lifetime_earned": 0    }  ],  "tiers": [    {      "program_id": "string",      "level": "string",      "since": "2019-08-24T14:15:22Z"    }  ],  "segments": [    "string"  ],  "counters": {    "property1": 0,    "property2": 0  },  "counter_windows": {    "property1": {      "window": "none",      "period_key": "string",      "all_time": 0,      "ready": true    },    "property2": {      "window": "none",      "period_key": "string",      "all_time": 0,      "ready": true    }  },  "challenges": [    {      "challenge_id": "string",      "period_key": "string",      "count": 0,      "status": "string"    }  ],  "issuances": [    {      "id": "string",      "reward_id": "string",      "status": "string",      "expires_at": "2019-08-24T14:15:22Z"    }  ],  "aliases": [    {      "alias": "string",      "kind": "anonymous",      "customer_id": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "collection_links": {    "challenges": "string",    "issuances": "string"  },  "summary_limit": 50,  "has_more": {    "challenges": true,    "issuances": true  }}

Identify an alias; active account movement additionally requires a secret key with customers:merge

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

Length1 <= length

Header Parameters

Idempotency-Key*string

Required. Official clients generate a UUID when omitted by the caller.

Length1 <= length <= 255

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length

X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

alias*string

Length1 <= length <= 200

Response Body

`application/json`

curl -X POST "https://example.com/customers/string/aliases" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "alias": "anonymous_42"  }'

{  "alias": {    "alias": "string",    "kind": "anonymous",    "customer_id": "string",    "created_at": "2019-08-24T14:15:22Z"  },  "merged_from": "string"}

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

Authorization

secretKey

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

Length1 <= length

Response Body

`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

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Query Parameters

limit?integer

Range1 <= value <= 200

Default50

cursor?string

Lengthlength <= 2048

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length

X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/attribute_definitions"

{  "data": [    {      "id": "string",      "key": "string",      "type": "string",      "description": "string",      "pii": true,      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string",  "has_more": true}

Declare or update an attribute definition by key; Location reads the collection

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Header Parameters

Idempotency-Key*string

Required. Official clients generate a UUID when omitted by the caller.

Length1 <= length <= 255

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length

X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

key*string

Match^[a-z][a-z0-9_]{0,63}$

type*string

Value in

"string"
"number"
"boolean"
"timestamp"

description?|null

pii?boolean

Response Body

`application/json`

curl -X POST "https://example.com/attribute_definitions" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "key": "favorite_genre",    "type": "string",    "pii": false  }'

{  "id": "string",  "key": "string",  "type": "string",  "description": "string",  "pii": true,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

All challenge progress for a customer

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

Length1 <= length

Query Parameters

limit?integer

Range1 <= value <= 200

Default50

cursor?string

Lengthlength <= 2048

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length

X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/customers/string/challenge_progress"

{  "data": [    {      "customer_id": "string",      "challenge_id": "string",      "period_key": "string",      "count": 0,      "status": "string"    }  ],  "next_cursor": "string",  "has_more": true}

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

Length1 <= length

key*string

birthday, anniversary, an operator-defined key, or the read-only signup

Match^[a-z][a-z0-9_]{0,31}$

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length

X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/customers/string/dates/string"

{  "customer_id": "string",  "key": "string",  "month": -9007199254740991,  "day": -9007199254740991,  "year": -9007199254740991,  "set_by": "customer",  "set_at": "2019-08-24T14:15:22Z",  "change_count": -9007199254740991,  "customer_change_allowed_at": "2019-08-24T14:15:22Z",  "editable": true}

Set or change a date of a customer

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

Length1 <= length

key*string

birthday, anniversary, an operator-defined key, or the read-only signup

Match^[a-z][a-z0-9_]{0,31}$

Header Parameters

Idempotency-Key*string

Required. Official clients generate a UUID when omitted by the caller.

Length1 <= length <= 255

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length

X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

month*integer

Range1 <= value <= 12

day*integer

Range1 <= value <= 31

year?|

Optional. Without a year, 29 February is accepted.

set_by?string

Recorded provenance; defaults to operator.

Value in

"operator"
"import"

Response Body

`application/json`

curl -X POST "https://example.com/customers/string/dates/string" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "month": 3,    "day": 14  }'

{  "customer_id": "string",  "key": "string",  "month": -9007199254740991,  "day": -9007199254740991,  "year": -9007199254740991,  "set_by": "customer",  "set_at": "2019-08-24T14:15:22Z",  "change_count": -9007199254740991,  "customer_change_allowed_at": "2019-08-24T14:15:22Z",  "editable": true}

Remove a date of a customer

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

Length1 <= length

key*string

birthday, anniversary, an operator-defined key, or the read-only signup

Match^[a-z][a-z0-9_]{0,31}$

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length

X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

`application/json`

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

Empty

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

421application/json

422application/json

429application/json

500application/json

200application/json

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

421application/json

422application/json

429application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

421application/json

422application/json

429application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

421application/json

422application/json

429application/json

500application/json

204

400application/json

401application/json

403application/json

404application/json

409application/json

421application/json

422application/json

429application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

421application/json

422application/json

429application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

421application/json

422application/json

429application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

421application/json

422application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`