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.