Sopmi Ticket API
Connect your ticketing platform to Sopmi so that event organizers can reward their ambassadors for every ticket they sell.
Overview
Sopmi is an ambassador platform for events. Organizers run ticket missions: each ambassador gets a personal code, shares it with friends and followers, and earns points for every ticket sold with that code. Points are later exchanged for rewards.
Your platform sells the tickets, so you know which code was used. This API lets you:
- fetch the ambassador codes of an organizer, so you can accept them in your shop (for example as a discount or tracking code);
- report each paid order that used a code, so Sopmi credits the right ambassador;
- report refunds, so Sopmi takes those points back.
You never receive personal data about ambassadors, and Sopmi never needs personal data about ticket buyers. A code and an order ID are enough.
How it works
Base URL: https://api.sopmi.app/v1. All requests and responses are JSON over HTTPS.
Authentication
Every request needs the organizer's API key in the Authorization header:
Authorization: Bearer spk_3f9a…(68 characters in total)
Each key belongs to exactly one organizer and only gives access to that organizer's missions, codes and sales. If you work for several organizers, store one key per organizer.
Keys are never accepted in the URL. A request with ?key= is rejected, so keys do not end up in logs.
Security
- Keys are stored as a SHA-256 hash. Sopmi shows a key once when it is created. Lost keys cannot be recovered; the organizer creates a new one.
- Revocable. The organizer can revoke a key at any time. Requests with a revoked key return
401immediately. - Least privilege. A key can only read codes and report sales and refunds for its own organizer. It cannot read ambassadors' names, emails or points.
- Server to server only. The API sends no CORS headers. Never put a key in a browser, app or public repository.
- Idempotent. Sales are unique per
order_id. Retrying the same request never credits points twice. - Brute-force protection. After 20 requests with an invalid key from the same IP address within a minute, further invalid requests get
429. Valid keys are never blocked by this, so one revoked key cannot take down your other organizers. IP addresses are stored only as a hash. - Strict input. Unknown endpoints, wrong methods, non-JSON bodies and bodies over 16 KB are rejected before any data is touched.
Found a security issue? Tell the organizer you work with, so they can report it to Sopmi through the Sopmi helpdesk.
Rate limits
Each key can make 120 requests per minute. Every response includes:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute (120). |
X-RateLimit-Remaining | Requests left in the current minute. |
Retry-After | Only on 429 and 503: seconds to wait before retrying. |
X-Request-Id | Unique ID of the request. Include it when you contact support. |
Requests with an invalid key are limited to 20 per minute per IP address. Requests with a valid key only count towards that key's own limit.
Recommended retry policy: retry 429, 500 and 503 with exponential backoff (for example 1, 2, 4, 8 seconds, at most 5 attempts). Do not retry other 4xx responses; fix the request instead. Because sales are idempotent, retrying a sale is always safe.
Errors
Errors always have the same shape:
{
"error": { "code": "invalid_request", "message": "order_id is required (max 200 characters)." },
"request_id": "6c1f2c8e-3f0a-4c8f-9a51-2f9a1c0b7d11"
}
| Status | Code | When |
|---|---|---|
| 400 | invalid_request | A field is missing or invalid, or the key was sent in the URL. |
| 401 | unauthorized | The key is missing, invalid or revoked. |
| 404 | not_found | Unknown endpoint, mission, code or order for this organizer. |
| 405 | method_not_allowed | The endpoint exists but not with this HTTP method. |
| 413 | payload_too_large | The body is larger than 16 KB. |
| 415 | unsupported_media_type | A POST without Content-Type: application/json. |
| 429 | rate_limited | Too many requests. Wait for Retry-After seconds. |
| 500 | server_error | Something went wrong on our side. Nothing was booked. Retry with backoff. |
| 503 | unavailable | Sopmi is temporarily unreachable. Retry with backoff. |
Check a key
Use this to validate a key when an organizer pastes it into your dashboard.
curl https://api.sopmi.app/v1/ping \
-H "Authorization: Bearer $SOPMI_KEY"
200 OK
{ "ok": true, "key_name": "Byticks", "request_id": "…" }
List missions
Returns the organizer's ticket missions, newest first. Archived missions are left out.
200 OK
{
"data": [
{
"id": "0b6c7a52-1f0e-4f43-9a0e-5f2d2b1c9e77",
"title": "Summer Festival 2027",
"status": "active",
"starts_at": "2027-05-01T00:00:00Z",
"ends_at": "2027-07-15T00:00:00Z",
"points_per_ticket": 10,
"codes": 48
}
],
"request_id": "…"
}
List codes
Returns the ambassador codes of a mission. A code is 8 lowercase letters and digits, for example k3m9x2pa. Ambassadors claim their code whenever they join, so new codes keep appearing.
| Query parameter | Description |
|---|---|
updated_since | Optional ISO 8601 timestamp. Only codes created after this moment. Use the newest created_at you have seen. |
curl "https://api.sopmi.app/v1/missions/0b6c7a52-1f0e-4f43-9a0e-5f2d2b1c9e77/codes?updated_since=2027-05-02T10:00:00Z" \
-H "Authorization: Bearer $SOPMI_KEY"
200 OK
{
"data": [
{ "code": "k3m9x2pa", "created_at": "2027-05-02T10:14:03Z" },
{ "code": "q7w2e8rt", "created_at": "2027-05-02T11:40:51Z" }
],
"request_id": "…"
}
Poll every few minutes with updated_since. Codes are case-insensitive: accept K3M9X2PA as well.
Report a sale
Report a paid order that used an ambassador code. Send it once the payment is confirmed, not when the order is created.
| Field | Type | Description |
|---|---|---|
code | string, required | The ambassador code used in the order. |
order_id | string, required | Your unique order ID, at most 200 characters. Used for idempotency and refunds. |
quantity | integer, optional | Number of tickets in the order that count, 1 to 1000. Default 1. |
curl https://api.sopmi.app/v1/sales \
-H "Authorization: Bearer $SOPMI_KEY" \
-H "Content-Type: application/json" \
-d '{ "code": "k3m9x2pa", "order_id": "ORD-104233", "quantity": 2 }'
201 Created
{
"data": { "order_id": "ORD-104233", "code": "k3m9x2pa", "quantity": 2, "points": 20,
"refunded": false, "duplicate": false },
"request_id": "…"
}
Sending the same order_id again returns 200 with "duplicate": true and the original values. No extra points are credited, even if the quantity differs.
Get a sale
Check whether Sopmi received an order. URL-encode the order ID.
200 OK
{
"data": { "order_id": "ORD-104233", "code": "k3m9x2pa", "quantity": 2, "points": 20,
"created_at": "2027-05-03T19:02:11Z", "refunded": false, "refunded_at": null },
"request_id": "…"
}
Report a refund
Report that a previously reported order was refunded or cancelled. Sopmi reverses the points of that order. Repeating the request is safe.
curl https://api.sopmi.app/v1/refunds \
-H "Authorization: Bearer $SOPMI_KEY" \
-H "Content-Type: application/json" \
-d '{ "order_id": "ORD-104233" }'
200 OK
{
"data": { "order_id": "ORD-104233", "refunded": true, "refunded_at": "2027-05-04T08:30:00Z", "points_reversed": 20 },
"request_id": "…"
}
Refunds apply to the whole order. If only some tickets of an order are refunded, report the refund and then report a new sale with a new order_id (for example ORD-104233-r1) for the remaining tickets.
Integration checklist
- Add a field in your organizer dashboard where the organizer pastes their Sopmi API key. Validate it with
GET /pingand store it encrypted. - Let the organizer pick a Sopmi mission (
GET /missions) for an event in your system. - Sync codes every few minutes (
GET /missions/{id}/codes?updated_since=…) and accept them in the shop. - On a paid order with a code:
POST /sales. Retry with backoff on429,5xxor a timeout. - On a refund or cancellation:
POST /refunds. - If a key returns
401, show the organizer that the connection stopped and ask for a new key.
Questions or want a test organizer? Ask the organizer you work with to contact Sopmi through the Sopmi helpdesk.
Changelog
| Date | Change |
|---|---|
| 18 November 2026 | Version 1: ping, missions, codes, sales, sale status and refunds. |