# Events

An event records one change. The same events go to your [webhooks](https://docs.creator-guard.com/webhooks/) and into `GET /v1/events`, which keeps the last **30 days**.

## The event object

| Field | Meaning |
|---|---|
| `id` | `evt_…`; the same for every retry and replay |
| `type` | One of the types below |
| `created_at` | When the change happened |
| `mode` | `live` or `test` |
| `api_version` | The contract version that rendered `data` |
| `sequence` | The `version` the object reached with this change — drop events whose `sequence` is not above the last one you applied for that object (`0` for `ping`) |
| `data.object` | The object as your account may see it when the event is read or delivered; an object that no longer exists is `{"id": …, "object": …, "deleted": true}` — except a removed photo, which `photo.removed` carries as it was when it was removed (stored with the event, without file or storage path) |
| `previous_attributes` | Only on events about a change: the changed fields by name, each `null` — except `stage` and `status`, which carry the old value. Never creator data. |

Unknown event types may be added within v1: ignore types you do not handle.

## Catalogue

| Type | When | `data.object` | Sent to | Scope to read it |
|---|---|---|---|---|
| `lead.created` | A lead was created (API or portal). | `Lead` | The account that owns the lead. | `leads:read` |
| `lead.updated` | Lead or listing fields changed; `previous_attributes` names them. | `Lead` | The account that owns the lead. | `leads:read` |
| `lead.stage_changed` | The lead moved to another stage; `previous_attributes.stage` is the old one. | `Lead` | The account that owns the lead. | `leads:read` |
| `lead.withdrawn` | The lead was withdrawn. | `Lead` | The account that owns the lead. | `leads:read` |
| `listing.approved` | Our review approved the listing; it is live for agencies. | `Lead` | The account that owns the lead. | `leads:read` |
| `photo.added` | A photo was added (API or portal). | `Photo` | The account that owns the lead. | `leads:read` |
| `photo.removed` | A photo was removed; `data.object` is the photo as it was, `url` is `null`. | `Photo` | The account that owns the lead. | `leads:read` |
| `consent.granted` | She granted consent on her page. | `Confirmations` | The account that owns the lead. | `leads:read` |
| `consent.revoked` | She revoked her consent. | `Confirmations` | The account that owns the lead. | `leads:read` |
| `age_confirmation.confirmed` | Her 18+ confirmation was recorded. | `Confirmations` | The account that owns the lead. | `leads:read` |
| `commission.created` | A commission was booked for your lead (her placement completed). | `Commission` | The account that owns the lead. | `earnings:read` |
| `commission.paid` | We paid a commission; `previous_attributes.status` is the old status. | `Commission` | The account that owns the lead. | `earnings:read` |
| `commission.voided` | A commission was voided; `previous_attributes.status` is the old status. | `Commission` | The account that owns the lead. | `earnings:read` |
| `agreement.published` | A new version of terms that apply to you was published. | `Agreement` | Every approved account of the type the terms are for; for `api_terms` and `api_dpa` every approved account. | `account:read` |
| `api_key.expiring` | A live key expires within 7 days (sent once per key). | `ApiKey` | The account of the key (live keys only). | `keys:manage` |
| `webhook_endpoint.disabled` | An endpoint was disabled after 72 hours of failed deliveries. | `WebhookEndpoint` | The account of the endpoint. | `webhooks:manage` |
| `offer.created` | We offered a creator to your agency (portal, matching or `POST /v1/test-helpers/offers`). | `Offer` | The agency the offer was made to. | `offers:read` |
| `offer.accepted` | The offer was accepted (API or portal); `previous_attributes.status` is the old status. | `Offer` | The agency the offer was made to. | `offers:read` |
| `offer.declined` | The offer was declined; `previous_attributes.status` is the old status. | `Offer` | The agency the offer was made to. | `offers:read` |
| `offer.expired` | The offer deadline passed before an accept or decline. | `Offer` | The agency the offer was made to. | `offers:read` |
| `offer.retracted` | We withdrew the offer (for example the listing was pulled or another agency won her). | `Offer` | The agency the offer was made to. | `offers:read` |
| `offer.reopened` | Your retracted offer is open again: the agency that won her undid its accept within the undo window. `previous_attributes.status` is `retracted`. | `Offer` | The agency the offer was made to. | `offers:read` |
| `offer.progressed` | Any other status change: contacted, in talks, signed, lost, or back to offered after your own undo; `previous_attributes.status` is the old status. | `Offer` | The agency the offer was made to. | `offers:read` |
| `offer.consent_revoked` | She withdrew her consent to share her profile. Sent for every offer your agency holds for her, whatever its status: delete what you keep of her listing and photos. Her listing is hidden (`listing` and `photo_count` `null`, photos refused) while the withdrawal stands, unless your placement of her is completed; an open offer is retracted as well (`offer.retracted`), and an accepted offer whose reservation still awaits payment is retracted with its reservation cancelled (`reservation.cancelled`). | `Offer` | Every agency holding an offer for her. | `offers:read` |
| `reservation.created` | An accept created a reservation (`awaiting_payment`). | `Reservation` | The agency the offer was made to. | `reservations:read` |
| `reservation.paid` | We received your payment: the reservation is `paid`, her contact is unlocked, the warranty runs. | `Reservation` | The agency the offer was made to. | `reservations:read` |
| `reservation.completed` | The warranty ended without a refund. | `Reservation` | The agency the offer was made to. | `reservations:read` |
| `reservation.refunded` | We refunded the fee after an accepted warranty claim. | `Reservation` | The agency the offer was made to. | `reservations:read` |
| `reservation.cancelled` | The reservation was cancelled: not paid in time, or the accept was undone. | `Reservation` | The agency the offer was made to. | `reservations:read` |
| `warranty_claim.created` | A warranty claim was filed on the reservation (API or portal). | `Reservation` | The agency the offer was made to. | `reservations:read` |
| `data_export.ready` | A creator's data export that your app requested is ready. Fetch the download link with her token: `GET /v1/creator/data-export/{id}`. | `DataRequestRef` | The account that owns the OAuth app whose creator token requested the export. | `oauth_apps:manage` |
| `job.completed` | An asynchronous job your app started finished (`succeeded` or `failed`). `GET /v1/jobs/{id}` with her token has the status and result. | `JobRef` | The account that owns the OAuth app whose creator token started the job. | `oauth_apps:manage` |
| `deletion_request.completed` | Creator Guard carried out the deletion request your app sent: her data is anonymised and her login and grants are gone. Stop processing her data in your systems. | `DataRequestRef` | The account that owns the OAuth app whose creator token sent the deletion request (even though her grant no longer exists). | `oauth_apps:manage` |
| `ping` | A test send (`POST /v1/webhook-endpoints/{id}/test`). | `{}` | Only the endpoint that was tested. | any key |

"The account that owns the lead" is the partner account that submitted it. **Agency events** go only to the agency the offer was made to: `offer.created`, `offer.accepted`, `offer.declined`, `offer.expired`, `offer.retracted`, `offer.reopened` and `offer.progressed` (scope `offers:read`), `reservation.created`, `reservation.paid`, `reservation.completed`, `reservation.refunded`, `reservation.cancelled` and `warranty_claim.created` (scope `reservations:read`) — see [Agencies](https://docs.creator-guard.com/agencies/). **Creator API events** (`data_export.ready`, `job.completed`, `deletion_request.completed`, scope `oauth_apps:manage`) go to the account that owns the OAuth app whose creator token started the work.

## Reading events

`GET /v1/events` lists the events of your key's mode, newest first, with `limit`, `starting_after` and `ending_before`. Filters: `type` (exact, or a group such as `lead.*`), `created_after`, `object` (the id of a lead, photo, commission, API key, webhook endpoint, offer, reservation, data request or job; confirmation events carry the lead id, warranty claims the reservation id). `GET /v1/events/{id}` reads one.

Any key may call both. The list only contains events whose object the key may read — the scope in the table above: a key with only `leads:read` sees lead, photo and confirmation events but no commissions. Reading one event directly without that scope answers [`403 insufficient_scope`](https://docs.creator-guard.com/errors/#insufficient_scope); an unknown id, another account's event or one older than 30 days answers [`404 not_found`](https://docs.creator-guard.com/errors/#not_found).
