Partner API documentation

How to connect your platform to the CreatoRain Partner API. The Partner API is in early access: access is by request.

Quick start

Getting started takes three steps.

Request access

Book a call with our team to request access. Once it is approved, we issue you a sandbox key, and a live key when you are ready.

Enroll a test store

Send POST /locations to the sandbox with your key in the Authorization header as a Bearer token. Sending the same request again returns the same store, so retries are safe.

Read it back

Read the store with GET /locations/{partner_location_id}, then its bookings and videos as they come in. Requests and responses are JSON.

Signed test webhook events are coming.

Authentication

Send your API key in the Authorization header as a Bearer token on every request: Authorization: Bearer YOUR_API_KEY. A request without a valid key gets 401 unauthorized.

Base URLs

Production: https://data.creatorain.com/partner/v1
Sandbox (test keys and test stores): https://datadev.creatorain.com/partner/v1

We issue each key when your access is approved and show it once: we keep only a hash of it, so store it in your secret manager. Live keys start with crp_live_ and sandbox keys with crp_test_. A key belongs to one account and one campaign.

We can limit a key to a list of up to 100 IP addresses or CIDR ranges. A call from any other address gets 403 forbidden_ip.

curl "$CREATORAIN_API_BASE/locations/store_123" \
  -H "Authorization: Bearer $CREATORAIN_API_KEY"

Conventions

Errors come back as { "error": { "code": "validation_error", "message": "…", "field": "address.state" } }. Branch on code; field tells you which input was refused.
A field the API does not recognize is refused with 400 validation_error, never silently ignored.
Times at a store carry the store's UTC offset, next to its IANA time zone. Times about the request itself, such as generated_at and a token's expires_at, are in UTC.
Lists return { "items": [...], "next_cursor": "…" }. limit is 50 by default and at most 200; pass next_cursor to get the next page.
Enrolling the same store with the same name and address returns 200 and the same store; pause, resume, terminate and acknowledge can be repeated. After a 500, retrying is safe.
A store's rules can set a follower range, overall or per platform, and the platforms its creators post on. Rules cannot select creators by ethnicity, age or gender: the API refuses them with 422.
preferred_language accepts en or zh.
A 500 error's message usually includes a reference. Quote it when you write to support@creatorain.com.

Endpoints reference

Every endpoint, grouped by what it does. All paths are under /partner/v1.

How data moves

Partner API endpoint list grouped as Calls you make, Reads and Events we send. Events are marked Coming. Beside it is one JSON booking from GET /reservations. — Calls and reads that cover stores, bookings, creators and billing. Each booking comes back as plain JSON. The picture shows sample data.

Calls you make
Enroll, change, pause, resume or end a store; acknowledge a booking; decide on sample creators; set your surcharge. 8 operations.
Reads
A store, its bookings, videos, creators and samples; all bookings; your summary, monthly counts, a price quote and your settings. 10 operations.
Events we sendComing
Signed webhooks for bookings, visits and published videos.

Stores

Enroll a store, change it, pause it, resume it or end it.

POST/locations
Enroll a store
GET/locations/{partner_location_id}
A store's status, opening hours, rules, progress and next visit
PATCH/locations/{partner_location_id}
Change a store's name, address, plan, dishes, language, opening hours, time zone or contact
POST/locations/{partner_location_id}/pause
Pause scheduling at a store
POST/locations/{partner_location_id}/resume
Resume scheduling at a store
POST/locations/{partner_location_id}/terminate
End a store's contract. This is final; its history is kept.

Bookings

Read creator bookings and record that the merchant saw one.

GET/locations/{partner_location_id}/reservations
One store's creator bookings
GET/reservations
Every store's bookings, filtered by date, status and whether they were acknowledged
POST/reservations/{reservation_id}/acknowledge
Record that the merchant saw a booking

Videos

Read the videos creators published for a store.

GET/locations/{partner_location_id}/content
One store's published videos

Reports

Your stores at a glance, and monthly counts.

GET/summary
All your stores in one call
GET/billing/monthly?month=YYYY-MM
Per-store counts for a month: videos published, completed visits and no-shows

Creators

See the creators named for a store and, for sample-review stores, approve a sample batch or ask for a new one.

GET/locations/{partner_location_id}/creators
The creators named for one store, from accepted on. No contact details.
GET/locations/{partner_location_id}/creator-samples
The current sample batch, for a store that uses sample review
POST/locations/{partner_location_id}/creator-samples/{batch_id}/decision
Approve the samples, or ask for a new batch

Pricing and settings

Quote the plan a merchant picks before you enroll the store, and set your surcharge once for all stores.

GET/pricing/quote
The finished price for the choices a merchant made, before the store is enrolled
GET/settings
Your surcharge per video
PUT/settings
Set your surcharge per video, once for all stores

Coming

Built, and not switched on yet.

POST/locations/{partner_location_id}/dashboard-token
Coming
A 30-minute read-only token for one store's page

Webhooks are coming: once they are switched on, we will send signed events about bookings, visits and published videos to an HTTPS endpoint you give us. Until then, read bookings and videos with the endpoints above.

States

The values the API returns for a store and a booking.

Store
Value	Meaning
`status`
`active`	Enrolled and scheduling visits
`paused`	No new visits are scheduled until you resume
`terminated`	Contract ended; final, history kept
`hours.state`
`found`	Opening hours are known
`missing`	Opening hours are not known yet; the store is on hold

Booking
Value	Meaning
`status`
`pending`	Requested, not yet confirmed
`confirmed`	Date and time set
`rejected`	Declined
`cancelled`	Called off
`completed`	The creator visited
`no_show`	The creator did not come
`acknowledged_kind`
`forwarded_to_manageracknowledged_self`	How the booking was acknowledged: forwarded to a manager, or by the merchant directly

Rate limits

Each API key can send 600 requests a minute by default, and we can raise it. There is no daily cap. Responses carry RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy headers; over the limit you get 429 with a Retry-After header.

Start building with the Partner API.

Book a call with our team to request access.