Orishare
API reference

List leagues, newest first

GET
/leagues

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Query Parameters

limit?integer
Range1 <= value <= 100
Default50
cursor?string
status?string

Value in

  • "draft"
  • "active"
  • "paused"
  • "archived"

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

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/leagues"
{  "data": [    {      "id": "string",      "key": "string",      "name": "string",      "status": "draft",      "config": {        "schema": "league/v1",        "tiers": [          {            "key": "string",            "name": "string",            "promote_count": 0,            "demote_count": 0,            "rewards": [],            "promotion_reward": {              "currency": "string",              "amount": 1            }          }        ],        "cohort_size": 5,        "period": {          "kind": "week",          "start_weekday": 1,          "start_minute": 0,          "timezone": "environment"        },        "score": {          "source": "direct"        },        "matching": "none",        "settle_delay_minutes": 10,        "min_score_to_promote": 1      },      "revision": -9007199254740991,      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string",  "has_more": true}

Create a draft league: tiers, promotion and demotion counts, cohort size, rewards

POST
/leagues

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.

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/leagues" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "key": "weekly",    "name": "Weekly league",    "config": {      "schema": "league/v1",      "tiers": [        {          "key": "bronze",          "name": "Bronze",          "promote_count": 10,          "demote_count": 0,          "rewards": [            {              "rank_from": 1,              "rank_to": 3,              "reward": [                {                  "currency": "gems",                  "amount": 50                },                {                  "type": "item",                  "item": "xp_boost_15m",                  "quantity": 1                }              ]            }          ]        },        {          "key": "silver",          "name": "Silver",          "promote_count": 7,          "demote_count": 5,          "rewards": [            {              "rank_from": 1,              "rank_to": 3,              "currency": "gems",              "amount": 100            }          ],          "promotion_reward": {            "currency": "gems",            "amount": 20          }        },        {          "key": "gold",          "name": "Gold",          "promote_count": 0,          "demote_count": 5,          "rewards": []        }      ],      "cohort_size": 30,      "period": {        "kind": "week",        "start_weekday": 1,        "start_minute": 0,        "timezone": "environment"      },      "score": {        "source": "direct"      },      "matching": "none",      "settle_delay_minutes": 10,      "min_score_to_promote": 1    }  }'
{  "id": "string",  "key": "string",  "name": "string",  "status": "draft",  "config": {    "schema": "league/v1",    "tiers": [      {        "key": "string",        "name": "string",        "promote_count": 0,        "demote_count": 0,        "rewards": [],        "promotion_reward": {          "currency": "string",          "amount": 1        }      }    ],    "cohort_size": 5,    "period": {      "kind": "week",      "start_weekday": 1,      "start_minute": 0,      "timezone": "environment"    },    "score": {      "source": "direct"    },    "matching": "none",    "settle_delay_minutes": 10,    "min_score_to_promote": 1  },  "revision": -9007199254740991,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Read one league by id or key

GET
/leagues/{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

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/leagues/string"
{  "id": "string",  "key": "string",  "name": "string",  "status": "draft",  "config": {    "schema": "league/v1",    "tiers": [      {        "key": "string",        "name": "string",        "promote_count": 0,        "demote_count": 0,        "rewards": [],        "promotion_reward": {          "currency": "string",          "amount": 1        }      }    ],    "cohort_size": 5,    "period": {      "kind": "week",      "start_weekday": 1,      "start_minute": 0,      "timezone": "environment"    },    "score": {      "source": "direct"    },    "matching": "none",    "settle_delay_minutes": 10,    "min_score_to_promote": 1  },  "revision": -9007199254740991,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Change the name or the configuration (If-Match); a new configuration applies from the next period

PATCH
/leagues/{id}

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
If-Match*string

Required revision, checked in the owning transaction.

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 PATCH "https://example.com/leagues/string" \  -H "Idempotency-Key: string" \  -H "If-Match: string" \  -H "Content-Type: application/json" \  -d '{    "name": "Weekly league"  }'
{  "id": "string",  "key": "string",  "name": "string",  "status": "draft",  "config": {    "schema": "league/v1",    "tiers": [      {        "key": "string",        "name": "string",        "promote_count": 0,        "demote_count": 0,        "rewards": [],        "promotion_reward": {          "currency": "string",          "amount": 1        }      }    ],    "cohort_size": 5,    "period": {      "kind": "week",      "start_weekday": 1,      "start_minute": 0,      "timezone": "environment"    },    "score": {      "source": "direct"    },    "matching": "none",    "settle_delay_minutes": 10,    "min_score_to_promote": 1  },  "revision": -9007199254740991,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Start a draft league: periods open and scores count

POST
/leagues/{id}/activate

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.

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/leagues/string/activate" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "expected_revision": 2  }'
{  "id": "string",  "key": "string",  "name": "string",  "status": "draft",  "config": {    "schema": "league/v1",    "tiers": [      {        "key": "string",        "name": "string",        "promote_count": 0,        "demote_count": 0,        "rewards": [],        "promotion_reward": {          "currency": "string",          "amount": 1        }      }    ],    "cohort_size": 5,    "period": {      "kind": "week",      "start_weekday": 1,      "start_minute": 0,      "timezone": "environment"    },    "score": {      "source": "direct"    },    "matching": "none",    "settle_delay_minutes": 10,    "min_score_to_promote": 1  },  "revision": -9007199254740991,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Pause a league: no new scores; open periods still settle

POST
/leagues/{id}/pause

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.

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/leagues/string/pause" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "expected_revision": 2  }'
{  "id": "string",  "key": "string",  "name": "string",  "status": "draft",  "config": {    "schema": "league/v1",    "tiers": [      {        "key": "string",        "name": "string",        "promote_count": 0,        "demote_count": 0,        "rewards": [],        "promotion_reward": {          "currency": "string",          "amount": 1        }      }    ],    "cohort_size": 5,    "period": {      "kind": "week",      "start_weekday": 1,      "start_minute": 0,      "timezone": "environment"    },    "score": {      "source": "direct"    },    "matching": "none",    "settle_delay_minutes": 10,    "min_score_to_promote": 1  },  "revision": -9007199254740991,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Resume a paused league

POST
/leagues/{id}/resume

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.

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/leagues/string/resume" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "expected_revision": 2  }'
{  "id": "string",  "key": "string",  "name": "string",  "status": "draft",  "config": {    "schema": "league/v1",    "tiers": [      {        "key": "string",        "name": "string",        "promote_count": 0,        "demote_count": 0,        "rewards": [],        "promotion_reward": {          "currency": "string",          "amount": 1        }      }    ],    "cohort_size": 5,    "period": {      "kind": "week",      "start_weekday": 1,      "start_minute": 0,      "timezone": "environment"    },    "score": {      "source": "direct"    },    "matching": "none",    "settle_delay_minutes": 10,    "min_score_to_promote": 1  },  "revision": -9007199254740991,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Archive a league for good

POST
/leagues/{id}/archive

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.

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/leagues/string/archive" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "expected_revision": 2  }'
{  "id": "string",  "key": "string",  "name": "string",  "status": "draft",  "config": {    "schema": "league/v1",    "tiers": [      {        "key": "string",        "name": "string",        "promote_count": 0,        "demote_count": 0,        "rewards": [],        "promotion_reward": {          "currency": "string",          "amount": 1        }      }    ],    "cohort_size": 5,    "period": {      "kind": "week",      "start_weekday": 1,      "start_minute": 0,      "timezone": "environment"    },    "score": {      "source": "direct"    },    "matching": "none",    "settle_delay_minutes": 10,    "min_score_to_promote": 1  },  "revision": -9007199254740991,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Add to (or correct) a customer's score in the current period of a direct-source league

POST
/leagues/{id}/contributions

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.

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/leagues/string/contributions" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "customer_id": "cust_0192f0c0a0b07c3d8e9f0a1b2c3d4e5f",    "amount": 25  }'
{  "entry": {    "period_id": "string",    "league_id": "string",    "customer_id": "string",    "cohort_id": "string",    "tier_index": -9007199254740991,    "score": -9007199254740991,    "score_updated_at": "2019-08-24T14:15:22Z",    "final_rank": -9007199254740991,    "outcome": "promoted",    "next_tier_index": -9007199254740991,    "reward": [      {        "kind": "rank",        "currency": "string",        "amount": -9007199254740991      }    ],    "reward_status": "none",    "reward_granted_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z"  },  "replayed": true}

List the periods of a league, newest first, with the configuration each one pinned

GET
/leagues/{id}/periods

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Query Parameters

limit?integer
Range1 <= value <= 100
Default50
cursor?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

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/leagues/string/periods"
{  "data": [    {      "id": "string",      "league_id": "string",      "key": "string",      "starts_at": "2019-08-24T14:15:22Z",      "ends_at": "2019-08-24T14:15:22Z",      "status": "open",      "league_revision": -9007199254740991,      "settled_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z",      "config": {        "schema": "league/v1",        "tiers": [          {            "key": "string",            "name": "string",            "promote_count": 0,            "demote_count": 0,            "rewards": [],            "promotion_reward": {              "currency": "string",              "amount": 1            }          }        ],        "cohort_size": 5,        "period": {          "kind": "week",          "start_weekday": 1,          "start_minute": 0,          "timezone": "environment"        },        "score": {          "source": "direct"        },        "matching": "none",        "settle_delay_minutes": 10,        "min_score_to_promote": 1      }    }  ],  "next_cursor": "string",  "has_more": true}

List the cohorts (groups of about 30) of a league period

GET
/league_periods/{id}/cohorts

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Query Parameters

limit?integer
Range1 <= value <= 100
Default50
cursor?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

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/league_periods/string/cohorts"
{  "data": [    {      "id": "string",      "league_id": "string",      "period_id": "string",      "tier_index": -9007199254740991,      "bucket": "string",      "seq": -9007199254740991,      "member_count": -9007199254740991,      "created_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string",  "has_more": true}

Read the ranked standings of one cohort, with customer ids

GET
/league_cohorts/{id}/standings

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

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/league_cohorts/string/standings"
{  "league": {    "id": "string",    "key": "string",    "name": "string"  },  "period": {    "id": "string",    "league_id": "string",    "key": "string",    "starts_at": "2019-08-24T14:15:22Z",    "ends_at": "2019-08-24T14:15:22Z",    "status": "open",    "league_revision": -9007199254740991,    "settled_at": "2019-08-24T14:15:22Z",    "created_at": "2019-08-24T14:15:22Z"  },  "cohort": {    "id": "string",    "league_id": "string",    "period_id": "string",    "tier_index": -9007199254740991,    "bucket": "string",    "seq": -9007199254740991,    "member_count": -9007199254740991,    "created_at": "2019-08-24T14:15:22Z"  },  "tier": {    "index": -9007199254740991,    "key": "string",    "name": "string"  },  "rows": [    {      "rank": -9007199254740991,      "score": -9007199254740991,      "display_name": "string",      "avatar_url": "string",      "is_self": true,      "zone": "promotion",      "outcome": "promoted",      "customer_id": "string"    }  ]}

List the members of a league and the tier each one holds

GET
/leagues/{id}/members

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Query Parameters

limit?integer
Range1 <= value <= 100
Default50
cursor?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

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/leagues/string/members"
{  "data": [    {      "league_id": "string",      "customer_id": "string",      "tier_index": -9007199254740991,      "status": "active",      "last_period_id": "string",      "joined_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string",  "has_more": true}

Take a customer out of a league (left) or let them back in (active)

POST
/leagues/{id}/members

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.

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/leagues/string/members" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "customer_id": "cust_0192f0c0a0b07c3d8e9f0a1b2c3d4e5f",    "status": "left"  }'
{  "league_id": "string",  "customer_id": "string",  "tier_index": -9007199254740991,  "status": "active",  "last_period_id": "string",  "joined_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Read a customer's tier, rank and last result in every active league

GET
/customers/{id}/leagues

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

The customer's id (cust_) or your external id for them

Length1 <= length <= 255

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

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/leagues"
{  "data": [    {      "league": {        "id": "string",        "key": "string",        "name": "string"      },      "tier": {        "index": -9007199254740991,        "key": "string",        "name": "string"      },      "member_status": "active",      "period": {        "id": "string",        "key": "string",        "starts_at": "2019-08-24T14:15:22Z",        "ends_at": "2019-08-24T14:15:22Z"      },      "seconds_left": -9007199254740991,      "paused": true,      "entry": {        "cohort_id": "string",        "tier": {          "index": -9007199254740991,          "key": "string",          "name": "string"        },        "score": -9007199254740991,        "rank": -9007199254740991,        "zone": "promotion"      },      "last_result": {        "period_id": "string",        "period_key": "string",        "rank": -9007199254740991,        "outcome": "promoted",        "tier": {          "index": -9007199254740991,          "key": "string",          "name": "string"        },        "next_tier": {          "index": -9007199254740991,          "key": "string",          "name": "string"        },        "reward": [          {            "kind": "rank",            "currency": "string",            "amount": -9007199254740991          }        ],        "reward_status": "none"      }    }  ]}

Leaderboards

Leaderboard contributions, standings and prize settlement.

Ledger

Currencies, manual adjustments, entries and balances.