# 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`](https://docs.creator-guard.com/errors/#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](https://docs.creator-guard.com/api-keys/#scopes).

Writes need the current **agency terms** ([`403 terms_not_accepted`](https://docs.creator-guard.com/errors/#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`](https://docs.creator-guard.com/errors/#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`](https://docs.creator-guard.com/errors/#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`](https://docs.creator-guard.com/errors/#offer_taken). A passed deadline is [`409 offer_expired`](https://docs.creator-guard.com/errors/#offer_expired), a withdrawn listing [`409 listing_unavailable`](https://docs.creator-guard.com/errors/#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`](https://docs.creator-guard.com/errors/#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`](https://docs.creator-guard.com/errors/#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`](https://docs.creator-guard.com/errors/#claim_exists); after the warranty it is [`409 warranty_expired`](https://docs.creator-guard.com/errors/#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](https://docs.creator-guard.com/events/) and [Webhooks](https://docs.creator-guard.com/webhooks/).

## Testing with a test key

With a `cg_test_` key everything happens in the sandbox ([Test mode](https://docs.creator-guard.com/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](https://docs.creator-guard.com/errors/); every field: [API reference](https://docs.creator-guard.com/reference/); what changed: [Changelog](https://docs.creator-guard.com/changelog/).
