Events
An event records one change. The same events go to your 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. 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; an unknown id, another account's event or one older than 30 days answers 404 not_found.