{"openapi":"3.1.0","info":{"title":"Searagraph API","version":"1.0.0","description":"Authenticate with `Authorization: Bearer <api key>`. Keys carry scopes; a missing scope is a 403 naming it.\n\nAgency-wide keys send `Searagraph-Business-Id` on every business endpoint (list ids with GET /businesses).\n\nLists are cursor-paginated: pass `next_cursor` back as `cursor` until it is null.\n\nWrites accept `Idempotency-Key`: a retry with the same key and body replays the first response.\n\nErrors: `{\"error\": {\"code\", \"message\", \"request_id\", \"details\"?}}`. Every response carries `X-Request-Id`.\n\nRate limit: 100 requests per 10 seconds per key (`X-RateLimit-*` headers; 429 + `Retry-After` when exceeded)."},"servers":[{"url":"/api/v1"}],"tags":[{"name":"Contacts"},{"name":"Tags"},{"name":"Custom fields"},{"name":"Forms"},{"name":"Segments"},{"name":"Automations"},{"name":"Campaigns"},{"name":"Businesses"},{"name":"Webhooks"},{"name":"Pipelines"},{"name":"Opportunities"}],"paths":{"/contacts":{"get":{"operationId":"listContacts","summary":"List contacts","description":"Live contacts (trash excluded) in creation order. With `tag_id`, a page can come back short — keep following next_cursor until it is null.\n\nRequires scope `contacts.read`.","tags":["Contacts"],"security":[{"apiKey":["contacts.read"]}],"x-required-scopes":["contacts.read"],"parameters":[{"name":"email","in":"query","required":false,"description":"Exact email match.","schema":{"type":"string","maxLength":320}},{"name":"phone","in":"query","required":false,"description":"Phone match (normalized to E.164 when possible).","schema":{"type":"string","maxLength":40}},{"name":"tag_id","in":"query","required":false,"description":"Only contacts carrying this tag.","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"updated_since","in":"query","required":false,"description":"Only contacts updated at or after this time.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"q","in":"query","required":false,"description":"Search name, email and phone.","schema":{"type":"string","maxLength":100}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/businessId"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"phone_e164":{"type":["string","null"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"address_line1":{"type":["string","null"]},"address_line2":{"type":["string","null"]},"city":{"type":["string","null"]},"state_region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]},"source":{"type":"string"},"opt_in_status":{"type":"string","enum":["granted","unknown","unsubscribed"]},"opted_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"custom":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Custom field values keyed by registry key."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","email","phone","phone_e164","first_name","last_name","address_line1","address_line2","city","state_region","postal_code","country","source","opt_in_status","opted_at","custom","tags","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as `cursor` to fetch the next page; null on the last page.","type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}},"post":{"operationId":"createContact","summary":"Create a contact","description":"Needs an email or a phone. A duplicate email is a 409 carrying `details.existing_id` — use upsert to update instead.\n\nRequires scope `contacts.write`.","tags":["Contacts"],"security":[{"apiKey":["contacts.write"]}],"x-required-scopes":["contacts.write"],"parameters":[{"$ref":"#/components/parameters/businessId"},{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"anyOf":[{"type":"string","maxLength":320},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"address_line1":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"address_line2":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"city":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"state_region":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"country":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"opt_in_status":{"description":"Email consent. A contact that unsubscribed can't be opted back in through the API.","type":"string","enum":["granted","unknown","unsubscribed"]},"custom":{"description":"Registry custom fields by key, validated by kind. `null` clears a key. Unknown keys are rejected.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"tags":{"description":"Tag names (created when missing) or tag ids. Requires the tags.write scope.","maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}}},"additionalProperties":false}}}},"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"phone_e164":{"type":["string","null"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"address_line1":{"type":["string","null"]},"address_line2":{"type":["string","null"]},"city":{"type":["string","null"]},"state_region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]},"source":{"type":"string"},"opt_in_status":{"type":"string","enum":["granted","unknown","unsubscribed"]},"opted_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"custom":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Custom field values keyed by registry key."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","email","phone","phone_e164","first_name","last_name","address_line1","address_line2","city","state_region","postal_code","country","source","opt_in_status","opted_at","custom","tags","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"409":{"$ref":"#/components/responses/conflict"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/contacts/lookup":{"get":{"operationId":"lookupContact","summary":"Find a contact by email or phone","description":"Pass exactly one of `email` or `phone`. Phone matches the oldest live contact with that E.164 number.\n\nRequires scope `contacts.read`.","tags":["Contacts"],"security":[{"apiKey":["contacts.read"]}],"x-required-scopes":["contacts.read"],"parameters":[{"name":"email","in":"query","required":false,"schema":{"type":"string","maxLength":320}},{"name":"phone","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"$ref":"#/components/parameters/businessId"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"phone_e164":{"type":["string","null"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"address_line1":{"type":["string","null"]},"address_line2":{"type":["string","null"]},"city":{"type":["string","null"]},"state_region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]},"source":{"type":"string"},"opt_in_status":{"type":"string","enum":["granted","unknown","unsubscribed"]},"opted_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"custom":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Custom field values keyed by registry key."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","email","phone","phone_e164","first_name","last_name","address_line1","address_line2","city","state_region","postal_code","country","source","opt_in_status","opted_at","custom","tags","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/contacts/{id}":{"get":{"operationId":"getContact","summary":"Get a contact","description":"Includes tags and custom field values.\n\nRequires scope `contacts.read`.","tags":["Contacts"],"security":[{"apiKey":["contacts.read"]}],"x-required-scopes":["contacts.read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessId"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"phone_e164":{"type":["string","null"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"address_line1":{"type":["string","null"]},"address_line2":{"type":["string","null"]},"city":{"type":["string","null"]},"state_region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]},"source":{"type":"string"},"opt_in_status":{"type":"string","enum":["granted","unknown","unsubscribed"]},"opted_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"custom":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Custom field values keyed by registry key."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","email","phone","phone_e164","first_name","last_name","address_line1","address_line2","city","state_region","postal_code","country","source","opt_in_status","opted_at","custom","tags","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}},"patch":{"operationId":"updateContact","summary":"Update a contact","description":"OVERWRITE semantics: each field sent replaces the stored value, `null` clears it, absent fields are untouched. custom keys are validated against the custom-field registry by kind; unknown keys are rejected.\n\nRequires scope `contacts.write`.","tags":["Contacts"],"security":[{"apiKey":["contacts.write"]}],"x-required-scopes":["contacts.write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessId"},{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"anyOf":[{"type":"string","maxLength":320},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"address_line1":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"address_line2":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"city":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"state_region":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"country":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"opt_in_status":{"description":"Email consent. A contact that unsubscribed can't be opted back in through the API.","type":"string","enum":["granted","unknown","unsubscribed"]},"custom":{"description":"Registry custom fields by key, validated by kind. `null` clears a key. Unknown keys are rejected.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"phone_e164":{"type":["string","null"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"address_line1":{"type":["string","null"]},"address_line2":{"type":["string","null"]},"city":{"type":["string","null"]},"state_region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]},"source":{"type":"string"},"opt_in_status":{"type":"string","enum":["granted","unknown","unsubscribed"]},"opted_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"custom":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Custom field values keyed by registry key."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","email","phone","phone_e164","first_name","last_name","address_line1","address_line2","city","state_region","postal_code","country","source","opt_in_status","opted_at","custom","tags","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"409":{"$ref":"#/components/responses/conflict"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}},"delete":{"operationId":"trashContact","summary":"Move a contact to trash","description":"Soft delete: the contact leaves every list and automation, and can be restored from Trash in the app (or by an upsert that matches it). Nothing is permanently deleted.\n\nRequires scope `contacts.write`.","tags":["Contacts"],"security":[{"apiKey":["contacts.write"]}],"x-required-scopes":["contacts.write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessId"},{"$ref":"#/components/parameters/idempotencyKey"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"trashed":{"type":"boolean","const":true}},"required":["id","trashed"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/contacts/upsert":{"post":{"operationId":"upsertContact","summary":"Create or update a contact","description":"Matches on email, then on E.164 phone (a phone match is used only when it can't clash with the body's email). A match is OVERWRITTEN with the fields sent (`null` clears); a match in trash is restored first. 201 when created, 200 when updated.\n\nRequires scope `contacts.write`.","tags":["Contacts"],"security":[{"apiKey":["contacts.write"]}],"x-required-scopes":["contacts.write"],"parameters":[{"$ref":"#/components/parameters/businessId"},{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"anyOf":[{"type":"string","maxLength":320},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"address_line1":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"address_line2":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"city":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"state_region":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"country":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"opt_in_status":{"description":"Email consent. A contact that unsubscribed can't be opted back in through the API.","type":"string","enum":["granted","unknown","unsubscribed"]},"custom":{"description":"Registry custom fields by key, validated by kind. `null` clears a key. Unknown keys are rejected.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"tags":{"description":"Tag names (created when missing) or tag ids. Requires the tags.write scope.","maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"phone_e164":{"type":["string","null"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"address_line1":{"type":["string","null"]},"address_line2":{"type":["string","null"]},"city":{"type":["string","null"]},"state_region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]},"source":{"type":"string"},"opt_in_status":{"type":"string","enum":["granted","unknown","unsubscribed"]},"opted_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"custom":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Custom field values keyed by registry key."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","email","phone","phone_e164","first_name","last_name","address_line1","address_line2","city","state_region","postal_code","country","source","opt_in_status","opted_at","custom","tags","created_at","updated_at"],"additionalProperties":false},"outcome":{"type":"string","enum":["created","updated"]},"restored":{"type":"boolean","description":"True when the match was in trash and was restored."}},"required":["data","outcome","restored"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"409":{"$ref":"#/components/responses/conflict"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/contacts/{id}/tags":{"post":{"operationId":"addContactTags","summary":"Tag a contact","description":"Each entry is a tag name (created when missing) or a tag id. Returns every tag on the contact.\n\nRequires scope `tags.write`.","tags":["Contacts"],"security":[{"apiKey":["tags.write"]}],"x-required-scopes":["tags.write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessId"},{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tags":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"description":"Tag names (created when missing) or tag ids."}},"required":["tags"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contact_id":{"type":"string","description":"Resource id (uuid)."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}}},"required":["contact_id","tags"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/contacts/{id}/tags/{tag_id}":{"delete":{"operationId":"removeContactTag","summary":"Untag a contact","description":"Removes the tag from this contact only (the tag itself stays). `removed` is false when it wasn't attached.\n\nRequires scope `tags.write`.","tags":["Contacts"],"security":[{"apiKey":["tags.write"]}],"x-required-scopes":["tags.write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"tag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessId"},{"$ref":"#/components/parameters/idempotencyKey"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contact_id":{"type":"string","description":"Resource id (uuid)."},"tag_id":{"type":"string","description":"Resource id (uuid)."},"removed":{"type":"boolean"}},"required":["contact_id","tag_id","removed"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/tags":{"get":{"operationId":"listTags","summary":"List tags","description":"Requires scope `tags.read`.","tags":["Tags"],"security":[{"apiKey":["tags.read"]}],"x-required-scopes":["tags.read"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/businessId"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","name","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as `cursor` to fetch the next page; null on the last page.","type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}},"post":{"operationId":"createTag","summary":"Create a tag","description":"A duplicate name is a 409 carrying `details.existing_id`.\n\nRequires scope `tags.write`.","tags":["Tags"],"security":[{"apiKey":["tags.write"]}],"x-required-scopes":["tags.write"],"parameters":[{"$ref":"#/components/parameters/businessId"},{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","name","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"409":{"$ref":"#/components/responses/conflict"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/tags/{id}":{"patch":{"operationId":"renameTag","summary":"Rename a tag","description":"Requires scope `tags.write`.","tags":["Tags"],"security":[{"apiKey":["tags.write"]}],"x-required-scopes":["tags.write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessId"},{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","name","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"409":{"$ref":"#/components/responses/conflict"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/custom-fields":{"get":{"operationId":"listCustomFields","summary":"List custom field definitions","description":"Requires scope `custom_fields.read`.","tags":["Custom fields"],"security":[{"apiKey":["custom_fields.read"]}],"x-required-scopes":["custom_fields.read"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/businessId"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"key":{"type":"string","description":"Immutable machine key (snake_case) — the key in contact.custom."},"label":{"type":"string"},"kind":{"type":"string","enum":["text","longtext","number","date","select","multiselect","checkbox"]},"options":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","key","label","kind","options","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as `cursor` to fetch the next page; null on the last page.","type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}},"post":{"operationId":"createCustomField","summary":"Create a custom field","description":"The key is derived from the label (snake_case) and is immutable. select / multiselect need options. A duplicate key is a 409.\n\nRequires scope `custom_fields.write`.","tags":["Custom fields"],"security":[{"apiKey":["custom_fields.write"]}],"x-required-scopes":["custom_fields.write"],"parameters":[{"$ref":"#/components/parameters/businessId"},{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":120,"description":"The key is derived from the label once, then immutable."},"kind":{"type":"string","enum":["text","longtext","number","date","select","multiselect","checkbox"]},"options":{"description":"Required for select / multiselect.","maxItems":50,"type":"array","items":{"type":"string","maxLength":120}}},"required":["label","kind"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"key":{"type":"string","description":"Immutable machine key (snake_case) — the key in contact.custom."},"label":{"type":"string"},"kind":{"type":"string","enum":["text","longtext","number","date","select","multiselect","checkbox"]},"options":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","key","label","kind","options","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"409":{"$ref":"#/components/responses/conflict"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/custom-fields/{id}":{"patch":{"operationId":"updateCustomField","summary":"Update a custom field","description":"Label and options only — key and kind are immutable (stored contact data references them).\n\nRequires scope `custom_fields.write`.","tags":["Custom fields"],"security":[{"apiKey":["custom_fields.write"]}],"x-required-scopes":["custom_fields.write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessId"},{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":120},"options":{"maxItems":50,"type":"array","items":{"type":"string","maxLength":120}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"key":{"type":"string","description":"Immutable machine key (snake_case) — the key in contact.custom."},"label":{"type":"string"},"kind":{"type":"string","enum":["text","longtext","number","date","select","multiselect","checkbox"]},"options":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","key","label","kind","options","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/forms":{"get":{"operationId":"listForms","summary":"List forms","description":"Requires scope `forms.read`.","tags":["Forms"],"security":[{"apiKey":["forms.read"]}],"x-required-scopes":["forms.read"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/businessId"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"},"status":{"type":"string","description":"active | paused | archived"},"submission_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"last_submission_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","name","status","submission_count","last_submission_at","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as `cursor` to fetch the next page; null on the last page.","type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/forms/{id}/submissions":{"get":{"operationId":"listFormSubmissions","summary":"List a form's submissions","description":"`status=partial` lists abandoned multi-page captures; default lists both.\n\nRequires scope `submissions.read`.","tags":["Forms"],"security":[{"apiKey":["submissions.read"]}],"x-required-scopes":["submissions.read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["complete","partial"]}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/businessId"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"form_id":{"type":"string","description":"Resource id (uuid)."},"contact_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"status":{"type":"string","enum":["complete","partial"]},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"page_reached":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","form_id","contact_id","status","data","page_reached","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as `cursor` to fetch the next page; null on the last page.","type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/segments":{"get":{"operationId":"listSegments","summary":"List segments","description":"Requires scope `segments.read`.","tags":["Segments"],"security":[{"apiKey":["segments.read"]}],"x-required-scopes":["segments.read"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/businessId"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"},"rules":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Segment rules (v1 or v2 shape)."},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","name","rules","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as `cursor` to fetch the next page; null on the last page.","type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/segments/{id}/contacts":{"get":{"operationId":"listSegmentContacts","summary":"List a segment's members","description":"Evaluates the segment's rules over live contacts in creation order. A page examines at most 5,000 contacts; when it stops there `truncated` is true and the page may be short — keep following next_cursor until it is null.\n\nRequires scope `segments.read`.","tags":["Segments"],"security":[{"apiKey":["segments.read"]}],"x-required-scopes":["segments.read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/businessId"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"phone_e164":{"type":["string","null"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"address_line1":{"type":["string","null"]},"address_line2":{"type":["string","null"]},"city":{"type":["string","null"]},"state_region":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":["string","null"]},"source":{"type":"string"},"opt_in_status":{"type":"string","enum":["granted","unknown","unsubscribed"]},"opted_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"custom":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Custom field values keyed by registry key."},"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false}},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","email","phone","phone_e164","first_name","last_name","address_line1","address_line2","city","state_region","postal_code","country","source","opt_in_status","opted_at","custom","tags","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as `cursor` to fetch the next page; null on the last page.","type":["string","null"]},"truncated":{"type":"boolean","description":"True when this page stopped at the scan bound before filling; keep following next_cursor."}},"required":["data","next_cursor","truncated"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/automations":{"get":{"operationId":"listAutomations","summary":"List automations","description":"Requires scope `automations.read`.","tags":["Automations"],"security":[{"apiKey":["automations.read"]}],"x-required-scopes":["automations.read"],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","active","paused","archived"]}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/businessId"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"trigger_type":{"type":"string"},"reentry_policy":{"type":"string","enum":["once","always"]},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","name","status","trigger_type","reentry_policy","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as `cursor` to fetch the next page; null on the last page.","type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/automations/{id}/enrollments":{"post":{"operationId":"enrollContact","summary":"Add a contact to an automation","description":"Only active automations accept enrollments, and the automation's re-entry policy applies: `once` refuses a contact that was ever enrolled, `always` refuses one that is currently active. Both refusals are a 409 with `details.reason`.\n\nRequires scope `automations.enroll`.","tags":["Automations"],"security":[{"apiKey":["automations.enroll"]}],"x-required-scopes":["automations.enroll"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessId"},{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["contact_id"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"automation_id":{"type":"string","description":"Resource id (uuid)."},"contact_id":{"type":"string","description":"Resource id (uuid)."},"status":{"type":"string","enum":["active","completed","exited","errored"]},"created_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","automation_id","contact_id","status","created_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"409":{"$ref":"#/components/responses/conflict"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/campaigns":{"get":{"operationId":"listCampaigns","summary":"List campaigns with stats","description":"Stats use the canonical definitions: rates are over delivered (delivery rate over sent), as percentages; null when the denominator is zero.\n\nRequires scope `campaigns.read`.","tags":["Campaigns"],"security":[{"apiKey":["campaigns.read"]}],"x-required-scopes":["campaigns.read"],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/businessId"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"},"status":{"type":"string","description":"draft | in_review | approved | sending | paused | sent | failed | cancelled"},"segment_id":{"type":"string","description":"Resource id (uuid)."},"template_id":{"type":"string","description":"Resource id (uuid)."},"scheduled_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"approved_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"sent_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"archived_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"stats":{"type":"object","properties":{"sent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Reached the email provider."},"delivered":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unique_opens":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unique_clicks":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unsubscribed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"delivery_rate":{"description":"Percentage 0–100; null when the denominator is zero.","type":["number","null"]},"open_rate":{"description":"Percentage 0–100; null when the denominator is zero.","type":["number","null"]},"click_rate":{"description":"Percentage 0–100; null when the denominator is zero.","type":["number","null"]},"click_to_open_rate":{"description":"Percentage 0–100; null when the denominator is zero.","type":["number","null"]},"unsubscribe_rate":{"description":"Percentage 0–100; null when the denominator is zero.","type":["number","null"]}},"required":["sent","delivered","unique_opens","unique_clicks","unsubscribed","delivery_rate","open_rate","click_rate","click_to_open_rate","unsubscribe_rate"],"additionalProperties":false},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","name","status","segment_id","template_id","scheduled_at","approved_at","sent_at","archived_at","stats","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as `cursor` to fetch the next page; null on the last page.","type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/businesses":{"get":{"operationId":"listBusinesses","summary":"List the businesses this key can act on","description":"Agency-level: needs no Searagraph-Business-Id. An agency-wide key sees every non-archived business in its agency (send one of these ids as Searagraph-Business-Id); a business key sees its own business.\n\nAny valid API key.","tags":["Businesses"],"security":[{"apiKey":[]}],"x-required-scopes":[],"parameters":[],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"},"status":{"type":"string"}},"required":["id","name","status"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/webhooks":{"get":{"operationId":"listWebhooks","summary":"List webhook subscriptions","description":"Agency-wide keys may omit Searagraph-Business-Id to act across the agency; with it the call is narrowed to that business (plus agency-wide subscriptions).\n\nRequires scope `webhooks.manage`.","tags":["Webhooks"],"security":[{"apiKey":["webhooks.manage"]}],"x-required-scopes":["webhooks.manage"],"parameters":[{"name":"status","in":"query","required":false,"description":"Only this status.","schema":{"type":"string","enum":["active","disabled"]}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/businessIdOptional"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"},"url":{"type":"string","description":"The https endpoint deliveries are POSTed to."},"event_types":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["business","agency"],"description":"`agency` = every business in the agency."},"business_id":{"description":"The business; null for agency-scope subscriptions.","type":["string","null"]},"status":{"type":"string","enum":["active","disabled"]},"disabled_reason":{"type":["string","null"]},"consecutive_failures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Deliveries that exhausted every retry in a row; the subscription is disabled at 20."},"created_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","name","url","event_types","scope","business_id","status","disabled_reason","consecutive_failures","created_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as `cursor` to fetch the next page; null on the last page.","type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}},"post":{"operationId":"createWebhook","summary":"Create a webhook subscription","description":"The URL must be https and resolve to a public address (checked now and at every delivery).\n\nThe response carries the `whsec_…` signing secret — the only time it is returned. Store it, then verify every delivery with it.\n\nA subscription never receives events from before it was created.\n\nAgency-wide keys may omit Searagraph-Business-Id to act across the agency; with it the call is narrowed to that business (plus agency-wide subscriptions).\n\nRequires scope `webhooks.manage`.","tags":["Webhooks"],"security":[{"apiKey":["webhooks.manage"]}],"x-required-scopes":["webhooks.manage"],"parameters":[{"$ref":"#/components/parameters/businessIdOptional"},{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"url":{"type":"string","minLength":1,"maxLength":2048,"description":"https only; must resolve to a public address."},"event_types":{"minItems":1,"type":"array","items":{"type":"string","enum":["contact.created","contact.updated","contact.dnd_updated","contact.tag_added","contact.tag_removed","contact.trashed","contact.restored","contact.erased","form.submitted","form.partial_captured","email.delivered","email.opened","email.clicked","email.bounced","email.complained","email.failed","email.unsubscribed","automation.enrolled","automation.completed","automation.exited","automation.errored","campaign.approved","campaign.scheduled","campaign.paused","campaign.resumed","campaign.cancelled","contract.sent","contract.viewed","contract.signed","contract.completed","contract.voided","invoice.posted","payment.received","payment.refunded","opportunity.created","opportunity.stage_changed","opportunity.status_changed","opportunity.updated","opportunity.archived"],"description":"A webhook event type from the event catalog."}},"scope":{"description":"Default `business` (needs a business). `agency` = all businesses; agency-wide keys only.","type":"string","enum":["business","agency"]}},"required":["name","url","event_types"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"},"url":{"type":"string","description":"The https endpoint deliveries are POSTed to."},"event_types":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["business","agency"],"description":"`agency` = every business in the agency."},"business_id":{"description":"The business; null for agency-scope subscriptions.","type":["string","null"]},"status":{"type":"string","enum":["active","disabled"]},"disabled_reason":{"type":["string","null"]},"consecutive_failures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Deliveries that exhausted every retry in a row; the subscription is disabled at 20."},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"secret":{"description":"The `whsec_…` signing secret — returned once. null on an Idempotency-Key replay (rotate to get a new one).","type":["string","null"]}},"required":["id","name","url","event_types","scope","business_id","status","disabled_reason","consecutive_failures","created_at","secret"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/webhooks/{id}":{"get":{"operationId":"getWebhook","summary":"Get a webhook subscription","description":"Never returns the secret — rotate it to issue a new one.\n\nRequires scope `webhooks.manage`.","tags":["Webhooks"],"security":[{"apiKey":["webhooks.manage"]}],"x-required-scopes":["webhooks.manage"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessIdOptional"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"},"url":{"type":"string","description":"The https endpoint deliveries are POSTed to."},"event_types":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["business","agency"],"description":"`agency` = every business in the agency."},"business_id":{"description":"The business; null for agency-scope subscriptions.","type":["string","null"]},"status":{"type":"string","enum":["active","disabled"]},"disabled_reason":{"type":["string","null"]},"consecutive_failures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Deliveries that exhausted every retry in a row; the subscription is disabled at 20."},"created_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","name","url","event_types","scope","business_id","status","disabled_reason","consecutive_failures","created_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}},"patch":{"operationId":"updateWebhook","summary":"Update a webhook subscription","description":"Change name, url, event_types or status. Scope is fixed at creation. Setting `status: active` re-enables a disabled subscription and resets its failure streak.\n\nRequires scope `webhooks.manage`.","tags":["Webhooks"],"security":[{"apiKey":["webhooks.manage"]}],"x-required-scopes":["webhooks.manage"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessIdOptional"},{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"url":{"type":"string","minLength":1,"maxLength":2048},"event_types":{"minItems":1,"type":"array","items":{"type":"string","enum":["contact.created","contact.updated","contact.dnd_updated","contact.tag_added","contact.tag_removed","contact.trashed","contact.restored","contact.erased","form.submitted","form.partial_captured","email.delivered","email.opened","email.clicked","email.bounced","email.complained","email.failed","email.unsubscribed","automation.enrolled","automation.completed","automation.exited","automation.errored","campaign.approved","campaign.scheduled","campaign.paused","campaign.resumed","campaign.cancelled","contract.sent","contract.viewed","contract.signed","contract.completed","contract.voided","invoice.posted","payment.received","payment.refunded","opportunity.created","opportunity.stage_changed","opportunity.status_changed","opportunity.updated","opportunity.archived"],"description":"A webhook event type from the event catalog."}},"status":{"description":"`active` re-enables and resets the failure streak.","type":"string","enum":["active","disabled"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"},"url":{"type":"string","description":"The https endpoint deliveries are POSTed to."},"event_types":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["business","agency"],"description":"`agency` = every business in the agency."},"business_id":{"description":"The business; null for agency-scope subscriptions.","type":["string","null"]},"status":{"type":"string","enum":["active","disabled"]},"disabled_reason":{"type":["string","null"]},"consecutive_failures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Deliveries that exhausted every retry in a row; the subscription is disabled at 20."},"created_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","name","url","event_types","scope","business_id","status","disabled_reason","consecutive_failures","created_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}},"delete":{"operationId":"deleteWebhook","summary":"Delete a webhook subscription","description":"Permanent: the subscription and its delivery log are removed; queued deliveries are dropped.\n\nRequires scope `webhooks.manage`.","tags":["Webhooks"],"security":[{"apiKey":["webhooks.manage"]}],"x-required-scopes":["webhooks.manage"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessIdOptional"},{"$ref":"#/components/parameters/idempotencyKey"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"deleted":{"type":"boolean","const":true}},"required":["id","deleted"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/webhooks/{id}/deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"List a subscription's deliveries","description":"Newest first. Each delivery is one event to this endpoint, with its retry state and last response.\n\nRequires scope `webhooks.manage`.","tags":["Webhooks"],"security":[{"apiKey":["webhooks.manage"]}],"x-required-scopes":["webhooks.manage"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"status","in":"query","required":false,"description":"Only this status.","schema":{"type":"string","enum":["pending","succeeded","retrying","failed"]}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/businessIdOptional"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Delivery id — the `webhook-id` header receivers de-duplicate on."},"event_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"event_type":{"type":["string","null"]},"status":{"type":"string","enum":["pending","succeeded","retrying","failed"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"last_status_code":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"last_error":{"type":["string","null"]},"response_snippet":{"description":"First 1 KB of the last response body.","type":["string","null"]},"next_attempt_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","event_id","event_type","status","attempts","last_status_code","last_error","response_snippet","next_attempt_at","delivered_at","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as `cursor` to fetch the next page; null on the last page.","type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/webhooks/{id}/rotate-secret":{"post":{"operationId":"rotateWebhookSecret","summary":"Rotate a subscription's signing secret","description":"Issues a new `whsec_…` secret, effective immediately, and returns it once. The old secret stops verifying.\n\nRequires scope `webhooks.manage`.","tags":["Webhooks"],"security":[{"apiKey":["webhooks.manage"]}],"x-required-scopes":["webhooks.manage"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessIdOptional"},{"$ref":"#/components/parameters/idempotencyKey"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"},"url":{"type":"string","description":"The https endpoint deliveries are POSTed to."},"event_types":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["business","agency"],"description":"`agency` = every business in the agency."},"business_id":{"description":"The business; null for agency-scope subscriptions.","type":["string","null"]},"status":{"type":"string","enum":["active","disabled"]},"disabled_reason":{"type":["string","null"]},"consecutive_failures":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Deliveries that exhausted every retry in a row; the subscription is disabled at 20."},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"secret":{"description":"The `whsec_…` signing secret — returned once. null on an Idempotency-Key replay (rotate to get a new one).","type":["string","null"]}},"required":["id","name","url","event_types","scope","business_id","status","disabled_reason","consecutive_failures","created_at","secret"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/pipelines":{"get":{"operationId":"listPipelines","summary":"List pipelines","description":"Active pipelines in display order, each with its active stages in board order.\n\nRequires scope `pipelines.read`.","tags":["Pipelines"],"security":[{"apiKey":["pipelines.read"]}],"x-required-scopes":["pipelines.read"],"parameters":[{"$ref":"#/components/parameters/businessId"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"is_default":{"type":"boolean","description":"New opportunities without a pipeline land here."},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"name":{"type":"string"},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Order within the pipeline (0 = first column)."}},"required":["id","name","position"],"additionalProperties":false},"description":"Active stages, in board order."},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","name","position","is_default","stages","created_at","updated_at"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/opportunities":{"get":{"operationId":"listOpportunities","summary":"List opportunities","description":"Non-archived opportunities in creation order.\n\nRequires scope `opportunities.read`.","tags":["Opportunities"],"security":[{"apiKey":["opportunities.read"]}],"x-required-scopes":["opportunities.read"],"parameters":[{"name":"pipeline_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"stage_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","won","lost","abandoned"]}},{"name":"contact_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"owner_user_id","in":"query","required":false,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"updated_since","in":"query","required":false,"description":"Only opportunities updated at or after this time.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/businessId"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"contact_id":{"type":"string","description":"Resource id (uuid)."},"pipeline_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"stage_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"name":{"type":"string"},"value_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Integer cents."},"currency":{"type":"string","description":"ISO 4217, lower case."},"status":{"type":"string","enum":["open","won","lost","abandoned"]},"lost_reason":{"type":["string","null"]},"owner_user_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"expected_close_date":{"description":"YYYY-MM-DD.","type":["string","null"]},"services":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["manual","intake","form","automation","api"]},"stage_entered_at":{"type":"string","description":"ISO 8601 timestamp."},"closed_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"archived_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","contact_id","pipeline_id","stage_id","name","value_cents","currency","status","lost_reason","owner_user_id","expected_close_date","services","source","stage_entered_at","closed_at","archived_at","created_at","updated_at"],"additionalProperties":false}},"next_cursor":{"description":"Pass as `cursor` to fetch the next page; null on the last page.","type":["string","null"]}},"required":["data","next_cursor"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}},"post":{"operationId":"createOpportunity","summary":"Create an opportunity","description":"Opens a deal for a contact. Without `pipeline_id` it lands in the default pipeline; without `stage_id`, in the pipeline's first stage. Send an Idempotency-Key to make retries safe.\n\nRequires scope `opportunities.write`.","tags":["Opportunities"],"security":[{"apiKey":["opportunities.write"]}],"x-required-scopes":["opportunities.write"],"parameters":[{"$ref":"#/components/parameters/businessId"},{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string","minLength":1,"maxLength":300},"value_cents":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Integer cents; null clears."},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"ISO 4217 code, e.g. usd."},"pipeline_id":{"description":"Omit for the default pipeline.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"stage_id":{"description":"Omit for the pipeline's first stage.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"owner_user_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"A user with access to the business; null = unassigned."},"expected_close_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"services":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}}},"required":["contact_id","name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"contact_id":{"type":"string","description":"Resource id (uuid)."},"pipeline_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"stage_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"name":{"type":"string"},"value_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Integer cents."},"currency":{"type":"string","description":"ISO 4217, lower case."},"status":{"type":"string","enum":["open","won","lost","abandoned"]},"lost_reason":{"type":["string","null"]},"owner_user_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"expected_close_date":{"description":"YYYY-MM-DD.","type":["string","null"]},"services":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["manual","intake","form","automation","api"]},"stage_entered_at":{"type":"string","description":"ISO 8601 timestamp."},"closed_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"archived_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","contact_id","pipeline_id","stage_id","name","value_cents","currency","status","lost_reason","owner_user_id","expected_close_date","services","source","stage_entered_at","closed_at","archived_at","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/opportunities/{id}":{"get":{"operationId":"getOpportunity","summary":"Get an opportunity","description":"Archived opportunities are returned too (`archived_at` set).\n\nRequires scope `opportunities.read`.","tags":["Opportunities"],"security":[{"apiKey":["opportunities.read"]}],"x-required-scopes":["opportunities.read"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessId"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"contact_id":{"type":"string","description":"Resource id (uuid)."},"pipeline_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"stage_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"name":{"type":"string"},"value_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Integer cents."},"currency":{"type":"string","description":"ISO 4217, lower case."},"status":{"type":"string","enum":["open","won","lost","abandoned"]},"lost_reason":{"type":["string","null"]},"owner_user_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"expected_close_date":{"description":"YYYY-MM-DD.","type":["string","null"]},"services":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["manual","intake","form","automation","api"]},"stage_entered_at":{"type":"string","description":"ISO 8601 timestamp."},"closed_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"archived_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","contact_id","pipeline_id","stage_id","name","value_cents","currency","status","lost_reason","owner_user_id","expected_close_date","services","source","stage_entered_at","closed_at","archived_at","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}},"patch":{"operationId":"updateOpportunity","summary":"Update, move or close an opportunity","description":"Fields sent replace the stored value (`null` clears); absent fields are untouched. `status` wins / loses / abandons / reopens the deal; `pipeline_id` / `stage_id` move it (appended to the end of the target column). Archived or archived-stage targets are refused (409 / 422). Archived opportunities must be restored first.\n\nRequires scope `opportunities.write`.","tags":["Opportunities"],"security":[{"apiKey":["opportunities.write"]}],"x-required-scopes":["opportunities.write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessId"},{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":300},"value_cents":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Integer cents; null clears."},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"ISO 4217 code, e.g. usd."},"owner_user_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"A user with access to the business; null = unassigned."},"expected_close_date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"services":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":200}},"status":{"description":"won / lost / abandoned close the deal; open reopens it.","type":"string","enum":["open","won","lost","abandoned"]},"lost_reason":{"description":"Only with status lost (or on a lost deal).","anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"pipeline_id":{"description":"Move to another pipeline (first stage unless stage_id is given).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"stage_id":{"description":"Move to this stage (appended to the end of the column).","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"contact_id":{"type":"string","description":"Resource id (uuid)."},"pipeline_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"stage_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"name":{"type":"string"},"value_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Integer cents."},"currency":{"type":"string","description":"ISO 4217, lower case."},"status":{"type":"string","enum":["open","won","lost","abandoned"]},"lost_reason":{"type":["string","null"]},"owner_user_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"expected_close_date":{"description":"YYYY-MM-DD.","type":["string","null"]},"services":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["manual","intake","form","automation","api"]},"stage_entered_at":{"type":"string","description":"ISO 8601 timestamp."},"closed_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"archived_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","contact_id","pipeline_id","stage_id","name","value_cents","currency","status","lost_reason","owner_user_id","expected_close_date","services","source","stage_entered_at","closed_at","archived_at","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"409":{"$ref":"#/components/responses/conflict"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/opportunities/{id}/archive":{"post":{"operationId":"archiveOpportunity","summary":"Archive an opportunity","description":"Removes it from boards and lists; nothing is deleted. Restore with POST /opportunities/{id}/restore.\n\nRequires scope `opportunities.write`.","tags":["Opportunities"],"security":[{"apiKey":["opportunities.write"]}],"x-required-scopes":["opportunities.write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessId"},{"$ref":"#/components/parameters/idempotencyKey"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"contact_id":{"type":"string","description":"Resource id (uuid)."},"pipeline_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"stage_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"name":{"type":"string"},"value_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Integer cents."},"currency":{"type":"string","description":"ISO 4217, lower case."},"status":{"type":"string","enum":["open","won","lost","abandoned"]},"lost_reason":{"type":["string","null"]},"owner_user_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"expected_close_date":{"description":"YYYY-MM-DD.","type":["string","null"]},"services":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["manual","intake","form","automation","api"]},"stage_entered_at":{"type":"string","description":"ISO 8601 timestamp."},"closed_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"archived_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","contact_id","pipeline_id","stage_id","name","value_cents","currency","status","lost_reason","owner_user_id","expected_close_date","services","source","stage_entered_at","closed_at","archived_at","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}},"/opportunities/{id}/restore":{"post":{"operationId":"restoreOpportunity","summary":"Restore an archived opportunity","description":"Back in place; when its stage or pipeline was archived meanwhile it moves to the first active stage (of its pipeline, else the default pipeline).\n\nRequires scope `opportunities.write`.","tags":["Opportunities"],"security":[{"apiKey":["opportunities.write"]}],"x-required-scopes":["opportunities.write"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"$ref":"#/components/parameters/businessId"},{"$ref":"#/components/parameters/idempotencyKey"}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"Resource id (uuid)."},"contact_id":{"type":"string","description":"Resource id (uuid)."},"pipeline_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"stage_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"name":{"type":"string"},"value_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Integer cents."},"currency":{"type":"string","description":"ISO 4217, lower case."},"status":{"type":"string","enum":["open","won","lost","abandoned"]},"lost_reason":{"type":["string","null"]},"owner_user_id":{"anyOf":[{"type":"string","description":"Resource id (uuid)."},{"type":"null"}]},"expected_close_date":{"description":"YYYY-MM-DD.","type":["string","null"]},"services":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["manual","intake","form","automation","api"]},"stage_entered_at":{"type":"string","description":"ISO 8601 timestamp."},"closed_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"archived_at":{"anyOf":[{"type":"string","description":"ISO 8601 timestamp."},{"type":"null"}]},"created_at":{"type":"string","description":"ISO 8601 timestamp."},"updated_at":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","contact_id","pipeline_id","stage_id","name","value_cents","currency","status","lost_reason","owner_user_id","expected_close_date","services","source","stage_entered_at","closed_at","archived_at","created_at","updated_at"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/not_found"},"422":{"$ref":"#/components/responses/validation_failed"},"429":{"$ref":"#/components/responses/rate_limited"},"500":{"$ref":"#/components/responses/internal"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"sg_live_…","description":"A Searagraph API key. Scopes granted to the key:","x-scopes":{"contacts.read":"Read contacts","contacts.write":"Create, update and trash contacts","tags.read":"Read tags","tags.write":"Create tags and tag or untag contacts","custom_fields.read":"Read custom field definitions","custom_fields.write":"Create and edit custom field definitions","forms.read":"Read forms","submissions.read":"Read form submissions","segments.read":"Read segments and their members","automations.read":"Read automations","automations.enroll":"Add contacts to automations","campaigns.read":"Read campaigns and their stats","webhooks.manage":"Manage webhook subscriptions","contacts.ingest":"Legacy contact ingest endpoint","pipelines.read":"Read pipelines and stages","opportunities.read":"Read opportunities","opportunities.write":"Create, update, move and archive opportunities"}}},"parameters":{"limit":{"name":"limit","in":"query","required":false,"description":"Page size (default 50, max 200).","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},"cursor":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from a previous page's next_cursor.","schema":{"type":"string"}},"businessId":{"name":"Searagraph-Business-Id","in":"header","required":false,"description":"Required for agency-wide keys: the business to act on. Business keys may omit it.","schema":{"type":"string","format":"uuid"}},"businessIdOptional":{"name":"Searagraph-Business-Id","in":"header","required":false,"description":"Optional for agency-wide keys: narrows the call to one business. Without it the call acts across the agency.","schema":{"type":"string","format":"uuid"}},"idempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the write safe to retry for 24 hours (same key + same body → same response).","schema":{"type":"string","maxLength":255}}},"responses":{"unauthorized":{"description":"Missing, invalid, revoked or expired API key.","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"forbidden":{"description":"The key lacks the required scope (named in the message), or can't act on that business.","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"not_found":{"description":"The resource doesn't exist in this business.","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"conflict":{"description":"Duplicate, already enrolled, or an Idempotency-Key request still in progress.","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"validation_failed":{"description":"The request is invalid; `details.fields` lists each problem.","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"rate_limited":{"description":"Too many requests; wait `Retry-After` seconds.","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Requests allowed per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in this window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"internal":{"description":"Unexpected server error (reported). Retry with the same Idempotency-Key.","headers":{"X-Request-Id":{"description":"Unique id for this request — quote it to support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","forbidden","not_found","conflict","validation_failed","rate_limited","internal"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}}}