Beta — the platform and this API are in beta. The rules on this page are binding; we may add features and tighten validation without notice.

Agencies: offers and reservations

Everything an agency does in the agency portal also works through the API: keep your search profile current, act on the creators we offer you, pay for the ones you accept and follow up with them. Your key is an agency key. It reaches the agency endpoints below and the referral endpoints (/v1/leads…) for creators you refer yourself.

The agency endpoints answer only agency keys. A referral partner's key gets 403 wrong_account_type — before the scope is checked, so a referrer key on GET /v1/offers sees wrong_account_type, not insufficient_scope.

Agency keys issued by Creator Guard carry account:read, account:write, agreements:write, earnings:read, leads:read, leads:write, offers:read, offers:write, reservations:read, reservations:write and search_profile:write. What each scope allows: API keys.

Writes need the current agency terms (403 terms_not_accepted with error.agreement_type). Check and accept them with GET /v1/agreements and POST /v1/agreements/agency_terms/accept. Reads never need terms.

Search profile and agency profile

GET /v1/search-profile returns what we match creators against. PUT /v1/search-profile replaces it: every field you leave out goes back to its default. Read it, change what you need, send the whole object back (with its ETag in If-Match if two systems may write).

flex says where a creator may be near your criteria instead of matching exactly. A key that is present means "may deviate", a missing key means "must match". Only the portal's levels are accepted:

Key Levels
age 3, 8, 20 (years outside your range)
revenue "zero" (no revenue yet is fine), 50, 100 (percent outside your range)
english 3, 5 (levels below your minimum), "any"
fee 25, 50, 100 (percent above your maximum fee)
split 10, 20, 30 (points above your maximum creator share)
stage "opposite" (the other creator stage is fine)
niches, platforms, content_types, languages {"also": [...]}: other values that are fine; [] = anything else is close

Any other level is 400 invalid_field with field set to flex.<key>. Money fields are US dollars only (currency: "USD"); revenue_min and revenue_max are whole dollars. max_placement_fee is compared with a listing's fee as it is, without currency conversion.

PATCH /v1/agency-profile changes only the fields you send. tier, verified_revenue and vetting are set by Creator Guard; sending them is 400 unknown_field.

Offers

When we match a creator to you, you get an offer (offer.created). Offers with a creator's profile reach your account only after your agency passed our vetting; GET /v1/agency-profile shows the state (vetting.status is registered, in_review or vetted, and vetting.waiting_matches counts the creators matched to you who wait for it). In the sandbox vetting.status is always vetted. An offer moves like this:

Status Meaning What you can do
offered Open until expires_at accept, decline (with a note of 50–500 characters)
accepted Reserved for you; pay the reservation undo-accept until undo_until while unpaid; mark-contacted or mark-signed once paid; mark-lost only while unpaid
contacted You reached her mark-in-talks, mark-signed
in_talks You are negotiating mark-signed
signed She signed with you —
lost It did not work out (outcome_reason) —
declined, expired, retracted Closed: you declined, the deadline passed, or we withdrew the offer —

A deal you paid for cannot be marked lost (409 deal_paid): if she does not work out, file a warranty claim on the reservation instead. Only a warranty claim or Creator Guard ends a paid deal.

Every offer carries next_actions, so you never have to re-implement these rules. An open offer whose deadline passed reads expired at once, even before our hourly job closes it. GET /v1/offers filters by status, created_since, updated_since and expires_before; PATCH /v1/offers/{id} keeps your own agency_note.

Accepting. POST /v1/offers/{id}/accept needs the current agency terms and the current warranty terms. Without them the answer is 403 terms_not_accepted with error.agreement_type: "warranty_terms" and nothing changes: read the version in GET /v1/agreements and accept it with POST /v1/agreements/warranty_terms/accept. Only one agency can win a creator: if another agency accepted her first, you get 409 offer_taken. A passed deadline is 409 offer_expired, a withdrawn listing 409 listing_unavailable. The accept creates a reservation (reservation on the offer) in awaiting_payment.

Undo. For a few minutes after accepting (undo_until; the length is accept_undo_minutes in GET /v1/settings) and before any payment, POST /v1/offers/{id}/undo-accept puts the offer back to offered and cancels the reservation. Later: 409 undo_window_passed.

Reservations

Status Meaning
awaiting_payment Transfer amount with payment_reference before payment_due_at
paid We received the fee. The creator's contact is unlocked; the warranty runs until warranty_until
completed The warranty ended without a refund
refunded We refunded you after an accepted warranty claim
cancelled Not paid in time, or you undid the accept

mark-contacted and mark-signed need a paid reservation (409 payment_pending before). GET /v1/reservations/{id}/creator returns her name, Instagram, other contact, platforms, followers, niche and creator number once the reservation is paid or completed; before payment it is 409 payment_pending.

Warranty claim. While the reservation is paid and the warranty runs, file one claim: POST /v1/reservations/{id}/warranty-claim with reason (creator_unreachable, no_show, false_data, contract_refused, other) and an optional note (up to 2,000 characters). A second claim is 409 claim_exists; after the warranty it is 409 warranty_expired. The claim shows in warranty_claim with its filed_at. Only your own claim counts: a refund Creator Guard decides on its own (and the sandbox refund helper) keeps warranty_claim at null and sends no warranty_claim.created.

What you see, and when

Open offer After payment
Creator number (CR-…) ✓ ✓
Creator name (creator_name; null before payment) — ✓
Listing: age, country, languages, content, availability, deal terms, placement fee ✓ ✓
Photos she agreed to share (signed links, 1 hour) ✓ ✓
Instagram, other contact, platforms, followers, niche — ✓
Who referred her, internal notes, her consent records never never

Once an offer is declined, expired, retracted or lost, its listing and photos are no longer shown (listing: null; photos answer 409 invalid_state) — unless you paid for her: after payment they stay visible.

"After payment" means a reservation of yours for her that is paid or completed; after a refund her name is null again.

She withdraws her consent. Then her listing goes offline for every agency: listing and photo_count are null and her photos answer 409 invalid_state on every offer, whatever its status — except for the agency whose placement of her is completed, which keeps the listing (her photos stay hidden). An open offer is also retracted, and so is an accepted offer whose reservation still awaits payment: that reservation is cancelled (offer.retracted, reservation.cancelled), and no reservation of hers can be paid while her withdrawal stands. A paid reservation is not touched. Every agency holding an offer for her receives offer.consent_revoked: delete what you stored of her listing and photos. If she gives her consent again, the normal rules apply again. Her contact after payment (GET /v1/reservations/{id}/creator) is not affected.

Events

offer.created, offer.accepted, offer.declined, offer.expired, offer.retracted, offer.reopened (your retracted offer is open again because the agency that won her undid its accept), offer.progressed (contacted, in talks, signed, lost, or back to offered after your own undo; previous_attributes.status has the old status), offer.consent_revoked (she withdrew her consent — every agency holding an offer for her, any status), reservation.created, reservation.paid, reservation.completed, reservation.refunded, reservation.cancelled and warranty_claim.created. They go only to your agency, and they fire the same way whether you act in the portal or through the API. Reading them needs offers:read (offer events) or reservations:read (reservation events) — see Events and Webhooks.

Testing with a test key

With a cg_test_ key everything happens in the sandbox (Test mode):

Request Plays Result
POST /v1/test-helpers/offers Our matching A synthetic creator offered to you (optional creator_name — shown after mark-paid — placement_fee, expires_in_hours)
POST /v1/test-helpers/reservations/{id}/mark-paid Our bookkeeping awaiting_payment → paid
POST /v1/test-helpers/reservations/{id}/complete The end of the warranty paid → completed
POST /v1/test-helpers/reservations/{id}/refund An accepted warranty claim paid → refunded
POST /v1/test-helpers/clock/advance Time passing, {"hours": n} (1–720) Offers expire, unpaid reservations are cancelled, warranties complete

A live key gets 404 not_found on every test helper. Known limit: POST /v1/test-helpers/reset empties the sandbox of your referral data, but your test offers and reservations as an agency stay in place; let them expire with clock/advance or ignore them.

Error codes: Errors; every field: API reference; what changed: Changelog.