{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/klozzo.com" } ], "info": { "name": "Klozzo API", "_postman_id": "86d37c12-dbae-4dcf-b648-f23153d96d0c", "description": "External integrator API for Klozzo. JSON over HTTPS, Bearer token auth.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "Lead capture", "description": "\nThe door a person comes in through when they raise their hand (U1-1).", "item": [ { "name": "Capture a lead", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/leads", "query": [], "raw": "{{baseUrl}}\/api\/leads" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"email\":\"ana.lopez@example.com\",\"phone\":\"+525555555555\",\"phone_country\":\"MX\",\"first_name\":\"Jonathan\",\"last_name\":\"Zapata\",\"company_name\":\"Klozzo\",\"timezone\":\"America\\\/Mexico_City\",\"source\":\"landing-verano\",\"interest\":\"Paquete de firmas\",\"landing_page\":\"https:\\\/\\\/klozzo.com\\\/producto-b\",\"referrer\":\"https:\\\/\\\/example.com\\\/blog\\\/precios\",\"utm\":{\"utm_source\":\"adwords\",\"utm_medium\":\"ppc\",\"utm_campaign\":\"verano\",\"utm_term\":\"y\",\"utm_content\":\"k\",\"gclid\":\"Cj0KCQjw\",\"fbclid\":\"m\",\"msclkid\":\"y\"},\"custom_field_values\":[]}" }, "description": "Records that a person raised their hand, whether or not you have ever seen\nthem before. Send what you have; the CRM decides what it means.\n\n**This endpoint never rejects a returning person.** Post the same email\ntwice and you get the same contact back, with `contact_created: false` \u2014\nwhere `POST \/api\/contacts` would answer `422` and drop everything you\nsent. Use this one for forms, ad callbacks and automations; use\n`\/api\/contacts` when you are deliberately writing a record.\n\n**Nothing you send creates schema.** A key in `custom_field_values` that\ndoes not match an existing custom field is not an error and does not\ncreate a field: it is kept on the touch and listed back to you in\n`unmapped_keys`, so a typo can never become a permanent column.\n\n**Existing data is not overwritten.** Each field applies its own write\nrule \u2014 most fill only when empty, attribution fields are written once and\nlocked. Anything refused comes back in `skipped` with the reason, so you\nnever have to guess whether your value landed.\n\nRepeat submissions of the same form by the same person, for the same\nthing, within 30 minutes count as one arrival. Send an `Idempotency-Key`\nheader to make that guarantee explicit and unbounded in time \u2014 see\n[Idempotency](#idempotency)." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": {\"contact\": {\"id\": \"01KZ2P...\", \"first_name\": \"Jonathan\"}, \"contact_created\": false, \"touch_id\": \"01KZ2Q...\", \"applied\": {\"last_name\": \"Zapata\"}, \"skipped\": {\"source\": \"immutable\"}, \"unmapped_keys\": [\"presupuesto_mensual\"]}}", "name": "Returning person, enriched" }, { "header": [], "code": 422, "body": "{\"message\": \"Hace falta al menos un correo electr\u00f3nico o un tel\u00e9fono para poder identificar a la persona.\", \"errors\": {\"email\": [\"Hace falta al menos un correo electr\u00f3nico o un tel\u00e9fono para poder identificar a la persona.\"]}}", "name": "No way to reach them" } ] } ] }, { "name": "Contacts", "description": "\nContacts are the core CRM record: leads, customers, and partners owned by the\nauthenticated user. All endpoints scope by user ownership; cross-user access\nis rejected with 403\/404 depending on policy.", "item": [ { "name": "List contact properties", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/properties", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/properties" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists every property a contact can carry in this location: the native ones\n(sent at the root of\nthe payload) and this location's custom fields (sent inside\n`custom_field_values`, keyed by `key`, `uuid` or numeric id).\n\nIt exists because otherwise the only way to know what you may send is to\nread the source: `\/api\/custom-fields` lists only the custom ones, and the\nnative ones were written down nowhere. Each entry says where it goes \u2014\n`location` is `root` for top-level fields and `custom_field_values` for\nthe rest \u2014 and which ones cannot be written here, with the alternative\nroute when there is one." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"key\":\"first_name\",\"label\":\"Nombre\",\"type\":\"text\",\"group\":\"native\",\"location\":\"root\",\"writable\":true,\"required\":true}]}", "name": "" } ] }, { "name": "List lead stages", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/lead-stages", "query": [], "raw": "{{baseUrl}}\/api\/lead-stages" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists the lead stages this account defines \u2014 the values `lead_stage_id`\naccepts.\n\n**Read this before you send `lead_stage_id`.** Lead stages are a catalogue\neach account defines for itself \u2014 not a fixed list shipped with the\nproduct \u2014 so the numbers are different in every account and there is no\nway to guess them. Call this endpoint once, keep the mapping, and send the\n`id`:\n\n```json\n{ \"lead_stage_id\": 1 }\n```\n\n`null` leaves the contact with no stage. An `id` from another account is\nrejected with `422`, which is the failure this endpoint exists to prevent.\n\nThey come back in the order the settings screen shows them (`position`),\nso you can render your own picker without re-sorting. `slug` is stable\nwhen somebody renames a stage \u2014 match on it if you keep a mapping in your\nown system. `contacts_count` is informational and moves on its own.\n\n`meta.usage` repeats the one-line instruction, so a caller that only ever\nlooks at the response body still finds out what to do with the `id`." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"name\":\"Nuevo\",\"slug\":\"nuevo\",\"color\":\"#22c55e\",\"position\":0,\"contacts_count\":42},{\"id\":2,\"name\":\"Contactado\",\"slug\":\"contactado\",\"color\":\"#3b82f6\",\"position\":1,\"contacts_count\":17},{\"id\":3,\"name\":\"Calificado\",\"slug\":\"calificado\",\"color\":null,\"position\":2,\"contacts_count\":4}],\"meta\":{\"usage\":\"Manda el `id` en `lead_stage_id` al crear o actualizar un contacto: {\\\"lead_stage_id\\\": 1}. `null` lo deja sin estado.\"}}", "name": "A location with the default stages" }, { "header": [], "code": 200, "body": "{\"data\":[],\"meta\":{\"usage\":\"Manda el `id` en `lead_stage_id` al crear o actualizar un contacto: {\\\"lead_stage_id\\\": 1}. `null` lo deja sin estado.\"}}", "name": "No location resolved for this token" }, { "header": [], "code": 403, "body": "{\"message\":\"This action is unauthorized.\"}", "name": "The token cannot read contacts" } ] }, { "name": "List contacts", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts", "query": [ { "key": "search", "value": "ada", "description": "Fragment matched against first\/last name, email, phone, company.", "disabled": false }, { "key": "contact_type", "value": "lead", "description": "Filter by type. One of `lead`, `customer`, `partner`.", "disabled": false }, { "key": "sort", "value": "created_at", "description": "Column to sort by (e.g. `created_at`, `last_name`). Defaults to newest first.", "disabled": false }, { "key": "direction", "value": "desc", "description": "Sort direction, `asc` or `desc`.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Rows per page. Default 25, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/contacts?search=ada&contact_type=lead&sort=created_at&direction=desc&per_page=25" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns a paginated list of contacts owned by the authenticated user.\nSupports full-text search across name, email, phone, and company." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":null,\"ulid\":null,\"first_name\":\"Morgan\",\"last_name\":\"Hirthe\",\"full_name\":\"Morgan Hirthe\",\"email\":\"dare.emelie@example.com\",\"email_verified_at\":null,\"email_verification_excluded\":false,\"email_verification_sent_at\":null,\"phone\":\"+12025550100\",\"phone_e164\":null,\"phone_country\":\"US\",\"phone_type\":null,\"has_whatsapp\":null,\"whatsapp_checked_at\":null,\"whatsapp_history_synced_until\":null,\"whatsapp_history_exhausted\":false,\"avatar_url\":null,\"additional_emails\":[],\"additional_phones\":[],\"company_name\":\"McLaughlin, Leuschke and Bauch\",\"contact_type\":\"lead\",\"timezone\":\"Asia\\\/Famagusta\",\"source\":\"import\",\"source_number\":null,\"date_of_birth\":\"2003-07-15\",\"dnd_all\":false,\"dnd_email\":false,\"dnd_sms\":false,\"dnd_calls\":false,\"dnd_voicemail\":false,\"dnd_gmb\":null,\"dnd_fb_messenger\":null,\"dnd_meta\":{},\"last_activity_at\":\"2026-08-17T14:16:42+00:00\",\"created_at\":null,\"updated_at\":null,\"owner_id\":null,\"lead_stage_id\":null},{\"id\":null,\"ulid\":null,\"first_name\":\"Lucienne\",\"last_name\":\"Haag\",\"full_name\":\"Lucienne Haag\",\"email\":\"lwisoky@example.net\",\"email_verified_at\":null,\"email_verification_excluded\":false,\"email_verification_sent_at\":null,\"phone\":\"+12025550101\",\"phone_e164\":null,\"phone_country\":\"US\",\"phone_type\":null,\"has_whatsapp\":null,\"whatsapp_checked_at\":null,\"whatsapp_history_synced_until\":null,\"whatsapp_history_exhausted\":false,\"avatar_url\":null,\"additional_emails\":[],\"additional_phones\":[],\"company_name\":\"Nitzsche-Ankunding\",\"contact_type\":\"customer\",\"timezone\":\"Asia\\\/Ho_Chi_Minh\",\"source\":\"import\",\"source_number\":null,\"date_of_birth\":\"2022-07-10\",\"dnd_all\":false,\"dnd_email\":false,\"dnd_sms\":false,\"dnd_calls\":false,\"dnd_voicemail\":false,\"dnd_gmb\":null,\"dnd_fb_messenger\":null,\"dnd_meta\":{},\"last_activity_at\":\"2026-08-03T06:11:58+00:00\",\"created_at\":null,\"updated_at\":null,\"owner_id\":null,\"lead_stage_id\":null}],\"links\":{\"first\":\"\\\/?page=1\",\"last\":\"\\\/?page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"links\":[{\"url\":null,\"label\":\"« Previous\",\"page\":null,\"active\":false},{\"url\":\"\\\/?page=1\",\"label\":\"1\",\"page\":1,\"active\":true},{\"url\":null,\"label\":\"Next »\",\"page\":null,\"active\":false}],\"path\":\"\\\/\",\"per_page\":25,\"to\":2,\"total\":2}}", "name": "" } ] }, { "name": "Create a contact", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts", "query": [], "raw": "{{baseUrl}}\/api\/contacts" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "multipart\/form-data" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "formdata", "formdata": [ { "key": "first_name", "value": "Ada", "type": "text", "description": "Contact first name." }, { "key": "last_name", "value": "Lovelace", "type": "text", "description": "Contact last name." }, { "key": "email", "value": "ada@example.com", "type": "text", "description": "Primary email; unique within scope if duplicate-block is on." }, { "key": "phone", "value": "+525555555555", "type": "text", "description": "E.164 with the country code \u2014 `+525555555555`. A local number is only accepted together with `phone_country`; without either the request is rejected. Stored normalised to E.164." }, { "key": "phone_country", "value": "MX", "type": "text", "description": "ISO-3166-1 alpha-2, e.g. `MX`. Only needed when `phone` has no `+` country code; ignored when it does." }, { "key": "phone_type", "value": "mobile", "type": "text", "description": "One of `mobile`, `home`, `work`, `other`." }, { "key": "company_name", "value": "Analytical Engines Ltd.", "type": "text", "description": "" }, { "key": "company_id", "value": "16", "type": "text", "description": "The id<\/code> of an existing record in the companies table." }, { "key": "contact_type", "value": "lead", "type": "text", "description": "One of `lead`, `customer`, `partner`." }, { "key": "lead_stage_id", "value": "16", "type": "text", "description": "The id<\/code> of an existing record in the lead_stages table." }, { "key": "timezone", "value": "America\/Mexico_City", "type": "text", "description": "IANA timezone." }, { "key": "source", "value": "web", "type": "text", "description": "Free-form acquisition source." }, { "key": "channel_integration_id", "value": "16", "type": "text", "description": "The id<\/code> of an existing record in the channel_integrations table." }, { "key": "date_of_birth", "value": "1815-12-10", "type": "text", "description": "ISO-8601 date." }, { "key": "additional_emails[0]", "value": "architecto", "type": "text", "description": "" }, { "key": "additional_phones[0]", "value": "architecto", "type": "text", "description": "" }, { "key": "dnd_all", "value": "", "type": "text", "description": "Master Do-Not-Disturb toggle." }, { "key": "dnd_email", "value": "", "type": "text", "description": "Block email for this person. Independent of `dnd_all`, which blocks everything." }, { "key": "dnd_sms", "value": "", "type": "text", "description": "Block SMS for this person." }, { "key": "dnd_calls", "value": "", "type": "text", "description": "Block outbound calls for this person." }, { "key": "dnd_voicemail", "value": "", "type": "text", "description": "Block leaving voicemail for this person." }, { "key": "dnd_gmb", "value": "", "type": "text", "description": "Block Google Business Messages for this person." }, { "key": "dnd_fb_messenger", "value": "", "type": "text", "description": "Block Facebook Messenger for this person." }, { "key": "auto_engage", "value": "1", "type": "text", "description": "Enable automated engagement workflows." }, { "key": "avatar", "src": [], "type": "file" } ] }, "description": "> **Coming from a form, an ad callback or an automation? Use\n> [`POST \/api\/leads`](#which-endpoint-do-i-use) instead.** This endpoint\n> answers `422` and drops the whole request when the person already\n> exists \u2014 including the campaign they came from and what they asked for\n> this time. `\/api\/leads` never rejects somebody who comes back.\n\nCreates a new contact owned by the authenticated user. Use it when you are\ndeliberately writing a record you know is new: a migration, an import\nscript, an internal tool.\n\nServer-side duplicate detection applies: if the location's\n`duplicate_mode = block`, a 422 is returned when email or phone collides\nwith an existing contact in the same scope." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"ulid\":null,\"first_name\":\"Christelle\",\"last_name\":\"Bailey\",\"full_name\":\"Christelle Bailey\",\"email\":\"rowan.gulgowski@example.com\",\"email_verified_at\":null,\"email_verification_excluded\":false,\"email_verification_sent_at\":null,\"phone\":\"+12025550102\",\"phone_e164\":null,\"phone_country\":\"CO\",\"phone_type\":null,\"has_whatsapp\":null,\"whatsapp_checked_at\":null,\"whatsapp_history_synced_until\":null,\"whatsapp_history_exhausted\":false,\"avatar_url\":null,\"additional_emails\":[],\"additional_phones\":[],\"company_name\":\"Dach-Gaylord\",\"contact_type\":\"customer\",\"timezone\":\"Africa\\\/Dakar\",\"source\":\"import\",\"source_number\":null,\"date_of_birth\":null,\"dnd_all\":false,\"dnd_email\":false,\"dnd_sms\":false,\"dnd_calls\":false,\"dnd_voicemail\":false,\"dnd_gmb\":null,\"dnd_fb_messenger\":null,\"dnd_meta\":{},\"last_activity_at\":null,\"created_at\":null,\"updated_at\":null,\"owner_id\":null,\"lead_stage_id\":null}}", "name": "" }, { "header": [], "code": 403, "body": "{\n \"message\": \"This action is unauthorized.\"\n}", "name": "not authorized" }, { "header": [], "code": 422, "body": "{\n \"message\": \"Ya existe un contacto con este correo electr\u00f3nico.\",\n \"errors\": { \"email\": [\"Ya existe un contacto con este correo electr\u00f3nico.\"] }\n}", "name": "duplicate email blocked" } ] }, { "name": "Fetch a contact", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/:id", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/:id", "variable": [ { "id": "id", "key": "id", "value": "42", "description": "The contact ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns one contact by id, with everything stored on it. Returns 404 if the\ncontact does not belong to the\nauthenticated user, 403 if policy denies access." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"ulid\":null,\"first_name\":\"Morgan\",\"last_name\":\"Hirthe\",\"full_name\":\"Morgan Hirthe\",\"email\":\"imclaughlin@example.org\",\"email_verified_at\":null,\"email_verification_excluded\":false,\"email_verification_sent_at\":null,\"phone\":\"+12025550103\",\"phone_e164\":null,\"phone_country\":\"MX\",\"phone_type\":null,\"has_whatsapp\":null,\"whatsapp_checked_at\":null,\"whatsapp_history_synced_until\":null,\"whatsapp_history_exhausted\":false,\"avatar_url\":null,\"additional_emails\":[],\"additional_phones\":[],\"company_name\":\"O'Keefe Inc\",\"contact_type\":\"lead\",\"timezone\":\"Pacific\\\/Tongatapu\",\"source\":\"manual\",\"source_number\":null,\"date_of_birth\":null,\"dnd_all\":false,\"dnd_email\":false,\"dnd_sms\":false,\"dnd_calls\":false,\"dnd_voicemail\":false,\"dnd_gmb\":null,\"dnd_fb_messenger\":null,\"dnd_meta\":{},\"last_activity_at\":\"2026-08-09T18:01:18+00:00\",\"created_at\":null,\"updated_at\":null,\"owner_id\":null,\"lead_stage_id\":null}}", "name": "" }, { "header": [], "code": 404, "body": "{ \"message\": \"No query results for model [App\\\\Models\\\\Contact].\" }", "name": "" } ] }, { "name": "Update a contact", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/:id", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/:id", "variable": [ { "id": "id", "key": "id", "value": "42", "description": "The contact ID." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"first_name\":\"Ada\",\"last_name\":\"Lovelace\",\"email\":\"ada@example.com\",\"phone\":\"+525555555555\",\"phone_country\":\"MX\",\"phone_type\":\"mobile\",\"additional_phones\":[\"architecto\"],\"company_name\":\"Analytical Engines Ltd.\",\"company_id\":16,\"contact_type\":\"customer\",\"lead_stage_id\":16,\"timezone\":\"America\\\/Mexico_City\",\"source\":\"web\",\"date_of_birth\":\"1815-12-10\",\"dnd_all\":false,\"dnd_email\":false,\"dnd_sms\":false,\"dnd_calls\":false,\"dnd_voicemail\":false,\"dnd_gmb\":false,\"dnd_fb_messenger\":false,\"custom_field_values\":[]}" }, "description": "Updates one contact by id, changing only the fields you send. Audit\nlog records the diff between old and new values. Avatar is not updatable here\n(re-upload via store or future endpoint)." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"ulid\":null,\"first_name\":\"Christelle\",\"last_name\":\"Bailey\",\"full_name\":\"Christelle Bailey\",\"email\":\"jdach@example.org\",\"email_verified_at\":null,\"email_verification_excluded\":false,\"email_verification_sent_at\":null,\"phone\":\"+12025550104\",\"phone_e164\":null,\"phone_country\":\"AR\",\"phone_type\":null,\"has_whatsapp\":null,\"whatsapp_checked_at\":null,\"whatsapp_history_synced_until\":null,\"whatsapp_history_exhausted\":false,\"avatar_url\":null,\"additional_emails\":[],\"additional_phones\":[],\"company_name\":\"Runte-Considine\",\"contact_type\":\"lead\",\"timezone\":\"America\\\/Indiana\\\/Tell_City\",\"source\":\"web\",\"source_number\":null,\"date_of_birth\":\"1985-10-22\",\"dnd_all\":false,\"dnd_email\":false,\"dnd_sms\":false,\"dnd_calls\":false,\"dnd_voicemail\":false,\"dnd_gmb\":null,\"dnd_fb_messenger\":null,\"dnd_meta\":{},\"last_activity_at\":\"2026-07-31T16:34:00+00:00\",\"created_at\":null,\"updated_at\":null,\"owner_id\":null,\"lead_stage_id\":null}}", "name": "" } ] }, { "name": "Delete a contact", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/:id", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/:id", "variable": [ { "id": "id", "key": "id", "value": "42", "description": "The contact ID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Soft-deletes one contact by id: it stops appearing anywhere in the CRM and is\nrecoverable. All associated activity,\nconversations, and tags remain intact for audit purposes." }, "response": [ { "header": [], "code": 200, "body": "{ \"message\": \"Contact deleted.\" }", "name": "" }, { "header": [], "code": 403, "body": "{ \"message\": \"This action is unauthorized.\" }", "name": "" } ] }, { "name": "Bulk action on contacts", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/bulk", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/bulk" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"action\":\"delete\",\"ids\":[16]}" }, "description": "Performs an action on multiple contacts in one call. Currently only `delete`\nis supported. Bulk delete is permanent (no soft-delete) and emits a single\naudit log entry covering all affected IDs." }, "response": [ { "header": [], "code": 200, "body": "{ \"message\": \"Bulk action completed.\" }", "name": "" }, { "header": [], "code": 422, "body": "{\n \"message\": \"The selected action is invalid.\",\n \"errors\": { \"action\": [\"The selected action is invalid.\"] }\n}", "name": "invalid action" } ] }, { "name": "Check whether a contact's email really exists", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/:contact_id\/verify-email", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/:contact_id\/verify-email", "variable": [ { "id": "contact_id", "key": "contact_id", "value": "42", "description": "The contact's id." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"driver\":\"zerobounce\"}" }, "description": "Queues a deliverability check against the configured verification\nprovider and answers `202` straight away \u2014 the result is not ready when\nthis call returns. Read `email_verification_status` on the contact (or\nwait for the `contact.updated` webhook) to find out how it went.\n\nUse it before a first send to a list you did not collect yourself. A\nbounce rate above a few percent is what gets a sending domain blocked, and\nthat is not something you undo in an afternoon.\n\nThe check costs money per address on most providers, so it is deliberately\na call you make, never something the CRM does on its own." }, "response": [ { "header": [], "code": 202, "body": "{\"message\":\"Email verification queued.\",\"contact_id\":42,\"status\":\"unverified\"}", "name": "" }, { "header": [], "code": 403, "body": "{\"message\":\"This action is unauthorized.\"}", "name": "Read-only role" }, { "header": [], "code": 422, "body": "{\"message\":\"Contact has no email to verify.\",\"errors\":{\"email\":[\"Contact has no email to verify.\"]}}", "name": "The contact has no email" }, { "header": [], "code": 422, "body": "{\"message\":\"Contact is excluded from email verification.\",\"errors\":{\"email\":[\"Contact is excluded from email verification.\"]}}", "name": "The contact is excluded from verification" } ] }, { "name": "Reassign contact owner", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/:contact_id\/owner", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/:contact_id\/owner", "variable": [ { "id": "contact_id", "key": "contact_id", "value": "42", "description": "The contact ID." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"owner_id\":7}" }, "description": "Transfers ownership of a contact to a different user. Pass `owner_id = null`\nto unassign. Requires the `reassignOwner` policy." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"ulid\":null,\"first_name\":\"Audra\",\"last_name\":\"Crooks\",\"full_name\":\"Audra Crooks\",\"email\":\"rempel.chadrick@example.org\",\"email_verified_at\":null,\"email_verification_excluded\":false,\"email_verification_sent_at\":null,\"phone\":\"+12025550105\",\"phone_e164\":null,\"phone_country\":\"CO\",\"phone_type\":null,\"has_whatsapp\":null,\"whatsapp_checked_at\":null,\"whatsapp_history_synced_until\":null,\"whatsapp_history_exhausted\":false,\"avatar_url\":null,\"additional_emails\":[],\"additional_phones\":[],\"company_name\":\"Gaylord and Sons\",\"contact_type\":\"customer\",\"timezone\":\"America\\\/Eirunepe\",\"source\":\"manual\",\"source_number\":null,\"date_of_birth\":\"1991-08-13\",\"dnd_all\":false,\"dnd_email\":false,\"dnd_sms\":false,\"dnd_calls\":false,\"dnd_voicemail\":false,\"dnd_gmb\":null,\"dnd_fb_messenger\":null,\"dnd_meta\":{},\"last_activity_at\":null,\"created_at\":null,\"updated_at\":null,\"owner_id\":null,\"lead_stage_id\":null}}", "name": "" } ] }, { "name": "Add a follower to a contact", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/:contact_id\/followers", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/:contact_id\/followers", "variable": [ { "id": "contact_id", "key": "contact_id", "value": "42", "description": "The contact ID." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"user_id\":7}" }, "description": "Followers receive notifications about activity on the contact. Idempotent:\nadding an existing follower is a no-op." }, "response": [ { "header": [], "code": 201, "body": "{\n \"message\": \"Follower added.\",\n \"followers\": [7, 12]\n}", "name": "" } ] }, { "name": "Remove a follower from a contact", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/:contact_id\/followers\/:user", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/:contact_id\/followers\/:user", "variable": [ { "id": "contact_id", "key": "contact_id", "value": "42", "description": "The contact ID." }, { "id": "user", "key": "user", "value": "7", "description": "ID of the user to remove." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Stops sending this user notifications about the contact. It does not touch\nownership: the owner is who the contact belongs to, a follower is only\nsomebody watching, and removing the last follower leaves the owner intact.\n\nIdempotent \u2014 removing somebody who was not following answers `200` all the\nsame, so a sync that cannot remember what it already did is safe." }, "response": [ { "header": [], "code": 200, "body": "{\n \"message\": \"Follower removed.\",\n \"followers\": [12]\n}", "name": "" } ] }, { "name": "List a contact's do-not-disturb settings", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/:contact_id\/dnd-settings", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/:contact_id\/dnd-settings", "variable": [ { "id": "contact_id", "key": "contact_id", "value": "42", "description": "The contact's id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists the do-not-disturb settings of one contact: one entry per channel\nthis person has asked not to be reached on. An empty\nlist means nothing is blocked \u2014 the absence of a row is the permission.\n\n`is_active` is the field to read: a setting can exist and be inactive\nbecause it was scheduled until a date that has already passed." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":9,\"contact_id\":42,\"channel\":\"sms\",\"enabled\":true,\"scheduled_until\":null,\"set_by\":3,\"set_at\":\"2026-08-23T17:04:00+00:00\",\"is_active\":true}]}", "name": "" }, { "header": [], "code": 404, "body": "{\"message\":\"No query results for model [App\\\\Models\\\\Contact].\"}", "name": "Not yours, or does not exist" } ] }, { "name": "Block a channel for a contact", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/:contact_id\/dnd-settings", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/:contact_id\/dnd-settings", "variable": [ { "id": "contact_id", "key": "contact_id", "value": "42", "description": "The contact's id." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"channel\":\"architecto\",\"enabled\":true,\"scheduled_until\":\"2052-09-18\"}" }, "description": "Records that this person does not want to be reached on one channel. The\nCRM checks it before every send, so blocking a channel here stops\nmessages queued by anything \u2014 a sequence, an automation, an agent typing\nin the inbox.\n\nSending the same `channel` twice updates the existing setting instead of\ncreating a second one, so a retry is safe.\n\nPass `scheduled_until` for a temporary block (\"not until after the\nholidays\"); leave it out for an indefinite one. Every change is written to\nthe audit log with who made it \u2014 consent decisions have to be provable." }, "response": [ { "header": [], "code": 201, "body": "{\"data\":{\"id\":9,\"contact_id\":42,\"channel\":\"sms\",\"enabled\":true,\"scheduled_until\":null,\"set_by\":3,\"set_at\":\"2026-08-23T17:04:00+00:00\",\"is_active\":true}}", "name": "" }, { "header": [], "code": 403, "body": "{\"message\":\"This action is unauthorized.\"}", "name": "Role without consent permissions" }, { "header": [], "code": 422, "body": "{\"message\":\"The selected channel is invalid.\",\"errors\":{\"channel\":[\"The selected channel is invalid.\"]}}", "name": "Unknown channel" } ] }, { "name": "Unblock a channel for a contact", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/:contact_id\/dnd-settings\/:dndSetting_id", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/:contact_id\/dnd-settings\/:dndSetting_id", "variable": [ { "id": "contact_id", "key": "contact_id", "value": "42", "description": "The contact's id." }, { "id": "dndSetting_id", "key": "dndSetting_id", "value": "9", "description": "The setting's id, from the list endpoint." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Removes the setting, which means the channel is open again. Use it when\nsomebody opts back in \u2014 never to \"clean up\" a list, because a deleted\nblock is a lost consent decision and the audit entry is the only trace\nleft of it.\n\nA setting that belongs to another contact answers `404`, even if the id\nexists." }, "response": [ { "header": [], "code": 200, "body": "{\"message\":\"DND setting removed.\"}", "name": "" }, { "header": [], "code": 403, "body": "{\"message\":\"This action is unauthorized.\"}", "name": "Role without consent permissions" }, { "header": [], "code": 404, "body": "{\"message\":\"Not Found\"}", "name": "The setting belongs to another contact" } ] }, { "name": "Read a contact's custom field values", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/:contact_id\/custom-field-values", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/:contact_id\/custom-field-values", "variable": [ { "id": "contact_id", "key": "contact_id", "value": "42", "description": "The contact's id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the custom field values of one contact as a flat object keyed by\nthe field's `key` \u2014 the same keys you send when\nwriting. Fields the contact has never been given a value for are simply\nabsent; there is no `null` placeholder for them.\n\nTo find out which keys exist in this account, call\n`GET \/api\/contacts\/properties` (everything a contact can carry) or\n`GET \/api\/custom-fields` (the custom ones with their type and options)." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"presupuesto_mensual\":\"25000\",\"canal_preferido\":\"whatsapp\"}}", "name": "" }, { "header": [], "code": 404, "body": "{\"message\":\"No query results for model [App\\\\Models\\\\Contact].\"}", "name": "Not visible from your location" } ] }, { "name": "Write a contact's custom field values", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/:contact_id\/custom-field-values", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/:contact_id\/custom-field-values", "variable": [ { "id": "contact_id", "key": "contact_id", "value": "42", "description": "The contact's id." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"values\":{\"presupuesto_mensual\":\"25000\"}}" }, "description": "Writes the custom field values of one contact. Send the values you want to\nset inside `values`, keyed by the field's\n`key`, `uuid` or numeric id. **Only the keys you send are touched** \u2014\nthis is a merge, not a replacement, so omitting a field leaves it alone\nand there is no way to accidentally blank the rest of the record.\n\nUnlike `POST \/api\/leads`, an unknown key here is an **error**, not\nsomething kept aside: this endpoint exists to write values on purpose, so\na typo is a bug worth stopping. You get a `422` naming every key that did\nnot match, and nothing is written.\n\nValues are validated against the field's own type \u2014 a date field rejects\n`\"ma\u00f1ana\"`, a dropdown rejects an option that is not on its list.\n\nCustom fields belong to the **location**, not to whoever created them:\na field another agent added is yours to write too." }, "response": [ { "header": [], "code": 200, "body": "{\"message\":\"Custom field values synced.\"}", "name": "" }, { "header": [], "code": 403, "body": "{\"message\":\"This action is unauthorized.\"}", "name": "Read-only role" }, { "header": [], "code": 422, "body": "{\"message\":\"El campo personalizado \u00abpresupesto\u00bb no existe o no est\u00e1 disponible en tu cuenta.\",\"errors\":{\"values.presupesto\":[\"El campo personalizado \u00abpresupesto\u00bb no existe o no est\u00e1 disponible en tu cuenta.\"]}}", "name": "A key that does not exist" }, { "header": [], "code": 422, "body": "{\"message\":\"The values.fecha_de_alta is not a valid date.\",\"errors\":{\"values.fecha_de_alta\":[\"The values.fecha_de_alta is not a valid date.\"]}}", "name": "A value the field's type rejects" } ] }, { "name": "List a contact's activity timeline", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/:contact_id\/activity", "query": [ { "key": "per_page", "value": "25", "description": "Rows per page. Default 25, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).", "disabled": false }, { "key": "cursor", "value": "eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0", "description": "The `next_cursor` from the previous response.", "disabled": false }, { "key": "event_type[0]", "value": "page_visited", "description": "Only these event types.", "disabled": false }, { "key": "event_type[1]", "value": "form_submitted", "description": "Only these event types.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/contacts\/:contact_id\/activity?per_page=25&cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0&event_type[0]=page_visited&event_type[1]=form_submitted", "variable": [ { "id": "contact_id", "key": "contact_id", "value": "42", "description": "The contact's id." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists the activity of one contact, newest first: pages visited,\nforms submitted, calls, notes, tag changes, messages. It is the same feed\nthe contact screen shows.\n\n**Paginated by cursor, not by page number.** The timeline grows while you\nread it, and a page number would either repeat or skip events as new ones\narrive. Follow `next_cursor` until it comes back `null`; do not build\n`?page=2` by hand.\n\nFilter with `event_type` to sync one kind of thing \u2014 pass it more than\nonce for several. The payload shape depends on the event type, so read\n`event_type` before reaching into `payload`." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":881,\"event_type\":\"form_submitted\",\"subject_type\":\"contact\",\"subject_id\":42,\"actor_type\":null,\"actor_id\":null,\"location_id\":3,\"payload\":{\"form_id\":\"newsletter\",\"utm_source\":\"adwords\"},\"occurred_at\":\"2026-08-23T17:04:00+00:00\"}],\"next_cursor\":\"eyJpZCI6ODgxfQ\",\"prev_cursor\":null}", "name": "" }, { "header": [], "code": 404, "body": "{\"message\":\"No query results for model [App\\\\Models\\\\Contact].\"}", "name": "Not visible from your location" } ] } ] }, { "name": "Custom Fields", "description": "\nCustom fields extend contacts with user-defined attributes. The `type` controls\nUI rendering and validation. For `dropdown`, `options` must be provided.", "item": [ { "name": "List custom fields", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/custom-fields", "query": [], "raw": "{{baseUrl}}\/api\/custom-fields" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns all custom fields for the authenticated user's location, ordered by\n`sort_order` then alphabetically." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":null,\"key\":null,\"label\":null,\"name\":\"quidem\",\"type\":\"text\",\"write_policy\":\"fill_if_empty\",\"options\":null,\"default_value\":null,\"is_required\":false,\"sort_order\":6,\"created_at\":null,\"updated_at\":null},{\"id\":null,\"key\":null,\"label\":null,\"name\":\"autem\",\"type\":\"date\",\"write_policy\":\"fill_if_empty\",\"options\":null,\"default_value\":null,\"is_required\":false,\"sort_order\":0,\"created_at\":null,\"updated_at\":null}]}", "name": "" } ] }, { "name": "Create a custom field", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/custom-fields", "query": [], "raw": "{{baseUrl}}\/api\/custom-fields" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Lifecycle stage\",\"key\":\"lifecycle_stage\",\"type\":\"dropdown\",\"write_policy\":\"fill_if_empty\",\"options\":[\"architecto\"],\"default_value\":\"trial\",\"is_required\":false,\"sort_order\":0}" }, "description": "Adds a property every contact in this location can carry. Create the field\n**before** you start sending its values: `POST \/api\/leads` keeps a value\nwhose key does not exist yet but does not create the field, and\n`PUT \/api\/contacts\/{id}\/custom-field-values` rejects it outright.\n\nThe `key` is what the API uses and it is **immutable** \u2014 renaming the\nfield later changes what people see, never what your code sends. Choose it\ndeliberately, or let it be derived from the name and read it back from the\nresponse.\n\n`write_policy` is the field's own rule for what happens when a new value\narrives for one that already has one. It is the reason a lead capture can\nenrich a record without ever destroying what a seller typed by hand." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"key\":null,\"label\":null,\"name\":\"eius\",\"type\":\"phone\",\"write_policy\":\"fill_if_empty\",\"options\":null,\"default_value\":null,\"is_required\":false,\"sort_order\":10,\"created_at\":null,\"updated_at\":null}}", "name": "" } ] }, { "name": "Fetch a custom field", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/custom-fields\/:uuid", "query": [], "raw": "{{baseUrl}}\/api\/custom-fields\/:uuid", "variable": [ { "id": "uuid", "key": "uuid", "value": "9", "description": "Custom field ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns one custom field by its UUID: its `key`, its type, its options if\nit is a\ndropdown, and its `write_policy`. Read it when a value you sent did not\nland the way you expected \u2014 nine times out of ten the answer is in\n`write_policy`, not in your payload." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"key\":null,\"label\":null,\"name\":\"nostrum\",\"type\":\"number\",\"write_policy\":\"fill_if_empty\",\"options\":null,\"default_value\":null,\"is_required\":false,\"sort_order\":6,\"created_at\":null,\"updated_at\":null}}", "name": "" }, { "header": [], "code": 404, "body": "{\"message\":\"No query results for model.\"}", "name": "Does not exist, or belongs to another location" } ] }, { "name": "Update a custom field", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/custom-fields\/:uuid", "query": [], "raw": "{{baseUrl}}\/api\/custom-fields\/:uuid", "variable": [ { "id": "uuid", "key": "uuid", "value": "9", "description": "Custom field ID." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Lifecycle stage\",\"label\":\"n\",\"type\":\"architecto\",\"write_policy\":\"last_write_wins\",\"options\":[\"architecto\"],\"default_value\":\"architecto\",\"is_required\":false,\"sort_order\":0}" }, "description": "Updates a custom field definition by its UUID. Renaming or changing `type`\ndoes not migrate existing stored values; callers\nare responsible for downstream cleanup. The `key` identifier is immutable." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"key\":null,\"label\":null,\"name\":\"et\",\"type\":\"url\",\"write_policy\":\"fill_if_empty\",\"options\":null,\"default_value\":null,\"is_required\":false,\"sort_order\":3,\"created_at\":null,\"updated_at\":null}}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\":\"Type no es una opci\u00f3n v\u00e1lida.\",\"errors\":{\"type\":[\"Type no es una opci\u00f3n v\u00e1lida.\"]}}", "name": "A type that does not exist" }, { "header": [], "code": 422, "body": "{\"message\":\"Falta options cuando type es dropdown.\",\"errors\":{\"options\":[\"Falta options cuando type es dropdown.\"]}}", "name": "A dropdown with no options" }, { "header": [], "code": 422, "body": "{\"message\":\"El valor de key ya est\u00e1 en uso.\",\"errors\":{\"key\":[\"El valor de key ya est\u00e1 en uso.\"]}}", "name": "A key already used in this location" } ] }, { "name": "Delete a custom field", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/custom-fields\/:uuid", "query": [], "raw": "{{baseUrl}}\/api\/custom-fields\/:uuid", "variable": [ { "id": "uuid", "key": "uuid", "value": "9", "description": "Custom field ID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Deletes a custom field definition by its UUID, so the field stops being\noffered anywhere in the CRM. Stored values on existing contacts are not\nremoved automatically (orphaned values remain queryable by ID)." }, "response": [ { "header": [], "code": 200, "body": "{ \"message\": \"Custom field deleted.\" }", "name": "" } ] } ] }, { "name": "Tags", "description": "\nTags are user-scoped labels attachable to contacts. Each tag has a name and an\noptional hex color. Tag deletion against an in-use tag returns 409 unless\n`force=true` is sent.", "item": [ { "name": "List tags", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/tags", "query": [], "raw": "{{baseUrl}}\/api\/tags" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns all tags owned by the authenticated user, sorted alphabetically.\nEach tag includes the count of associated contacts." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":null,\"name\":\"aut\",\"slug\":null,\"color\":\"#a11e59\",\"location_id\":null,\"created_at\":null,\"updated_at\":null},{\"id\":null,\"name\":\"modi\",\"slug\":null,\"color\":\"#865450\",\"location_id\":null,\"created_at\":null,\"updated_at\":null}]}", "name": "" } ] }, { "name": "Create a tag", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/tags", "query": [], "raw": "{{baseUrl}}\/api\/tags" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"VIP\",\"color\":\"#ff6b35\"}" }, "description": "Tags are the free-form way to group people: a campaign, an event, a list\nyou built by hand. Use them for something you will want to filter by later\nbut that has no value of its own \u2014 when the thing you want to record *has*\na value (\"budget\", \"plan\", \"renewal date\"), a custom field is what you\nwant instead.\n\nThe name is unique inside the location; creating one that already exists\nanswers `422` rather than a second tag with the same name." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"name\":\"nihil\",\"slug\":null,\"color\":\"#c8a15d\",\"location_id\":null,\"created_at\":null,\"updated_at\":null}}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\":\"Color no tiene un formato v\u00e1lido.\",\"errors\":{\"color\":[\"Color no tiene un formato v\u00e1lido.\"]}}", "name": "A colour that is not a hex code" }, { "header": [], "code": 422, "body": "{\"message\":\"El valor de name ya est\u00e1 en uso.\",\"errors\":{\"name\":[\"El valor de name ya est\u00e1 en uso.\"]}}", "name": "A name already used in this location" } ] }, { "name": "Fetch a tag", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/tags\/:id", "query": [], "raw": "{{baseUrl}}\/api\/tags\/:id", "variable": [ { "id": "id", "key": "id", "value": "3", "description": "Tag ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns one tag by id, with how many contacts carry it. Useful before deleting one: the\ncount is what tells you whether removing it is housekeeping or data loss." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"name\":\"adipisci\",\"slug\":null,\"color\":\"#f76df4\",\"location_id\":null,\"created_at\":null,\"updated_at\":null}}", "name": "" }, { "header": [], "code": 404, "body": "{\"message\":\"No query results for model.\"}", "name": "Does not exist, or belongs to another location" } ] }, { "name": "Update a tag", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/tags\/:id", "query": [], "raw": "{{baseUrl}}\/api\/tags\/:id", "variable": [ { "id": "id", "key": "id", "value": "3", "description": "Tag ID." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"VIP Customer\",\"color\":\"#ff6b35\"}" }, "description": "Updates a tag's name or colour by id. **Every contact carrying the tag sees\nthe new name immediately** \u2014 a tag is one row, not a copy per contact \u2014 so\nrenaming is how you fix a typo, never how you split a group in two." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"name\":\"accusantium\",\"slug\":null,\"color\":\"#902510\",\"location_id\":null,\"created_at\":null,\"updated_at\":null}}", "name": "" } ] }, { "name": "Delete a tag", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/tags\/:id", "query": [ { "key": "force", "value": "1", "description": "Detach from contacts and delete anyway.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/tags\/:id?force=1", "variable": [ { "id": "id", "key": "id", "value": "3", "description": "Tag ID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Deletes a tag by id. If the tag is attached to any contacts, returns 409\nunless `force=true` is\npassed, in which case the tag is detached from all contacts then deleted." }, "response": [ { "header": [], "code": 200, "body": "{ \"message\": \"Tag deleted.\" }", "name": "" }, { "header": [], "code": 409, "body": "{\n \"message\": \"Tag is in use.\",\n \"contacts_count\": 12,\n \"hint\": \"Pass force=true to detach and delete.\"\n}", "name": "tag in use" } ] } ] }, { "name": "Smart Lists", "description": "\nSmart Lists are saved filter+sort definitions that can be private to a user or\nshared across a location. `filters` is an array of clauses; `sort` defines the\ndefault ordering. Visibility is determined by the `is_shared` flag plus the\n`visibleTo` query scope.", "item": [ { "name": "List smart lists", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/smart-lists", "query": [], "raw": "{{baseUrl}}\/api\/smart-lists" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns smart lists visible to the authenticated user, ordered by `sort_order`\nthen alphabetically by name." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":null,\"location_id\":null,\"user_id\":3765,\"name\":\"aut adipisci\",\"filters\":[{\"field\":\"contact_type\",\"operator\":\"=\",\"value\":\"lead\"}],\"sort\":null,\"sort_order\":2,\"is_shared\":false,\"is_default\":false,\"created_at\":null,\"updated_at\":null},{\"id\":null,\"location_id\":null,\"user_id\":3766,\"name\":\"consequatur aut\",\"filters\":[{\"field\":\"contact_type\",\"operator\":\"=\",\"value\":\"lead\"}],\"sort\":null,\"sort_order\":7,\"is_shared\":false,\"is_default\":false,\"created_at\":null,\"updated_at\":null}]}", "name": "" } ] }, { "name": "Create a smart list", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/smart-lists", "query": [], "raw": "{{baseUrl}}\/api\/smart-lists" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Hot leads, last 7 days\",\"filters\":[{\"field\":\"contact_type\",\"operator\":\"eq\",\"value\":\"lead\"}],\"sort\":{\"field\":\"created_at\",\"direction\":\"desc\"},\"sort_order\":0,\"is_shared\":false,\"is_default\":false}" }, "description": "Creates a smart list: a saved question about contacts, not a saved answer.\nThe list stores the filters and the\nsort; who matches is worked out every time it is opened, so somebody who\nbecomes a hot lead tomorrow is in it tomorrow without anybody touching it.\n\nThat is the difference from a tag: a tag is something you put on a person,\na smart list is a rule that finds them.\n\nSet `is_shared` to give the whole team the list; leave it off and it is\nyours. Only one list per user can be `is_default`, and setting a new one\nclears the old." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"location_id\":null,\"user_id\":3767,\"name\":\"architecto eius\",\"filters\":[{\"field\":\"contact_type\",\"operator\":\"=\",\"value\":\"lead\"}],\"sort\":null,\"sort_order\":0,\"is_shared\":false,\"is_default\":false,\"created_at\":null,\"updated_at\":null}}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\":\"Falta filters.\",\"errors\":{\"filters\":[\"Falta filters.\"]}}", "name": "A list with no rule" }, { "header": [], "code": 422, "body": "{\"message\":\"Falta filters.0.operator.\",\"errors\":{\"filters.0.operator\":[\"Falta filters.0.operator.\"]}}", "name": "A clause missing its operator" } ] }, { "name": "Fetch a smart list", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/smart-lists\/:id", "query": [], "raw": "{{baseUrl}}\/api\/smart-lists\/:id", "variable": [ { "id": "id", "key": "id", "value": "5", "description": "Smart list ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Its filters and sort, not the contacts it matches \u2014 to get those, send the\nsame filters to `GET \/api\/contacts`. A list you cannot see (somebody\nelse's, unshared) answers `404`." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"location_id\":null,\"user_id\":3768,\"name\":\"aut adipisci\",\"filters\":[{\"field\":\"contact_type\",\"operator\":\"=\",\"value\":\"lead\"}],\"sort\":null,\"sort_order\":2,\"is_shared\":false,\"is_default\":false,\"created_at\":null,\"updated_at\":null}}", "name": "" }, { "header": [], "code": 404, "body": "{\"message\":\"No query results for model.\"}", "name": "Does not exist, or belongs to another location" } ] }, { "name": "Update a smart list", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/smart-lists\/:id", "query": [], "raw": "{{baseUrl}}\/api\/smart-lists\/:id", "variable": [ { "id": "id", "key": "id", "value": "5", "description": "Smart list ID." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Hot leads, last 14 days\",\"filters\":[{\"field\":\"architecto\",\"operator\":\"architecto\"}],\"sort\":{\"field\":\"architecto\",\"direction\":\"desc\"},\"sort_order\":2,\"is_shared\":true,\"is_default\":false}" }, "description": "Changes the rule, so it changes who the list finds from the next time\nanybody opens it \u2014 including everybody else's, if the list is shared.\nThere is no version history: the previous filters are gone.\n\nSending `filters` **replaces** them all; there is no way to add one clause\nwithout resending the rest." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"location_id\":null,\"user_id\":3769,\"name\":\"architecto eius\",\"filters\":[{\"field\":\"contact_type\",\"operator\":\"=\",\"value\":\"lead\"}],\"sort\":null,\"sort_order\":0,\"is_shared\":false,\"is_default\":false,\"created_at\":null,\"updated_at\":null}}", "name": "" } ] }, { "name": "Delete a smart list", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/smart-lists\/:id", "query": [], "raw": "{{baseUrl}}\/api\/smart-lists\/:id", "variable": [ { "id": "id", "key": "id", "value": "5", "description": "Smart list ID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Deletes a smart list by id, and only the list. **No contact is deleted** \u2014 a\nsmart list never owned\nanybody, it only found them \u2014 so this is always safe, and it is the one\ndestructive-looking call in this API that is not." }, "response": [ { "header": [], "code": 200, "body": "{ \"message\": \"Smart list deleted.\" }", "name": "" } ] } ] }, { "name": "Conversations", "description": "\nConversations are per-contact message threads spanning all channels (SMS, email,\nWhatsApp, etc.). A contact has at most one open conversation per location. New\ninbound or outbound messages auto-create the conversation if it does not exist.", "item": [ { "name": "List conversations for a contact", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/:contact_id\/conversations", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/:contact_id\/conversations", "variable": [ { "id": "contact_id", "key": "contact_id", "value": "42", "description": "Contact ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists the conversations of one contact, ordered by most recent activity.\nThere is typically\none per contact-location pair, but historical conversations remain queryable." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [\n {\n \"id\": 17,\n \"contact_id\": 42,\n \"location_id\": 1,\n \"last_message_at\": \"2026-06-05T13:42:00+00:00\",\n \"last_channel\": \"whatsapp\",\n \"unread_count\": 3\n }\n ]\n}", "name": "" } ] }, { "name": "Open or fetch a conversation for a contact", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/contacts\/:contact_id\/conversations", "query": [], "raw": "{{baseUrl}}\/api\/contacts\/:contact_id\/conversations", "variable": [ { "id": "contact_id", "key": "contact_id", "value": "42", "description": "Contact ID." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Opens a conversation for one contact, or hands back the one that already\nexists. Idempotent: returns the existing conversation for the contact-location pair\nwhen one already exists (200), or creates and returns a fresh one (201)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": { \"id\": 17, \"contact_id\": 42, \"location_id\": 1, \"last_message_at\": \"2026-06-05T13:42:00+00:00\", \"last_channel\": \"whatsapp\", \"unread_count\": 3 }\n}", "name": "already existed" }, { "header": [], "code": 201, "body": "{\n \"data\": {\n \"id\": 17,\n \"contact_id\": 42,\n \"location_id\": 1,\n \"last_message_at\": null,\n \"last_channel\": null,\n \"unread_count\": 0\n }\n}", "name": "newly created" } ] }, { "name": "Fetch a conversation", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/conversations\/:id", "query": [], "raw": "{{baseUrl}}\/api\/conversations\/:id", "variable": [ { "id": "id", "key": "id", "value": "17", "description": "Conversation ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns one conversation by id: the thread, the contact it belongs to and\nits channel. Use it to check\nthe state of a thread you were handed the id of; to read the messages,\ncall `GET \/api\/conversations\/{id}\/messages`, which is paginated because a\nWhatsApp thread is not." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"id\": 17,\n \"contact_id\": 42,\n \"location_id\": 1,\n \"last_message_at\": \"2026-06-05T13:42:00+00:00\",\n \"last_channel\": \"whatsapp\",\n \"unread_count\": 3\n }\n}", "name": "" }, { "header": [], "code": 403, "body": "{\"message\":\"This action is unauthorized.\"}", "name": "The contact behind it is not visible to you" }, { "header": [], "code": 404, "body": "{\"message\":\"No query results for model.\"}", "name": "Does not exist, or belongs to another location" } ] } ] }, { "name": "Messages", "description": "\nMessages are individual entries in a conversation. Each carries a `channel`\n(sms, email, whatsapp, etc.), `direction` (inbound or outbound), and lifecycle\ntimestamps (`sent_at`, `delivered_at`, `read_at`). Outbound messages are routed\nby `ChannelRouter` to the appropriate provider integration.", "item": [ { "name": "List messages in a conversation", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/conversations\/:conversation_id\/messages", "query": [ { "key": "per_page", "value": "50", "description": "Rows per page. Default 50, maximum 200. See [Lists, paging and filters](#lists-paging-and-filters).", "disabled": false }, { "key": "cursor", "value": "architecto", "description": "Opaque cursor from a previous response.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/conversations\/:conversation_id\/messages?per_page=50&cursor=architecto", "variable": [ { "id": "conversation_id", "key": "conversation_id", "value": "17", "description": "Conversation ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists the messages of one conversation, oldest first, cursor-paginated by\n`id`. For infinite scroll,\npage backwards using `prev_cursor`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [\n {\n \"id\": 9001,\n \"conversation_id\": 17,\n \"channel\": \"whatsapp\",\n \"direction\": \"outbound\",\n \"body\": \"Hi Ada, your appointment is confirmed.\",\n \"attachments\": null,\n \"status\": \"delivered\",\n \"provider_message_id\": \"wamid.HBgN...\",\n \"sent_at\": \"2026-06-05T13:42:00+00:00\",\n \"delivered_at\": \"2026-06-05T13:42:02+00:00\",\n \"read_at\": null,\n \"error\": null,\n \"user_id\": 7,\n \"created_at\": \"2026-06-05T13:42:00+00:00\"\n }\n ],\n \"next_cursor\": \"eyJpZCI6OTAwMSwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ\",\n \"prev_cursor\": null\n}", "name": "" }, { "header": [], "code": 404, "body": "{\"message\":\"No query results for model.\"}", "name": "Does not exist, or belongs to another location" } ] }, { "name": "Send a message", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/conversations\/:conversation_id\/messages", "query": [], "raw": "{{baseUrl}}\/api\/conversations\/:conversation_id\/messages", "variable": [ { "id": "conversation_id", "key": "conversation_id", "value": "17", "description": "Conversation ID." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"channel\":\"whatsapp\",\"body\":\"Hi Ada, your appointment is confirmed.\",\"attachments\":[\"architecto\"],\"recipient\":\"architecto\"}" }, "description": "Records the outbound message immediately (returning 201) and dispatches\ndelivery via the appropriate provider asynchronously. Poll the message\nresource for `delivered_at` \/ `read_at` updates, or subscribe to outbound\nwebhooks (`message.delivered`, `message.read`).\n\nIf `recipient` is omitted, it is inferred from the contact:\n- `email` \u2192 `contact.email`\n- everything else \u2192 `contact.phone_e164` or `contact.phone`" }, "response": [ { "header": [], "code": 201, "body": "{\n \"data\": {\n \"id\": 9001,\n \"conversation_id\": 17,\n \"channel\": \"whatsapp\",\n \"direction\": \"outbound\",\n \"body\": \"Hi Ada, your appointment is confirmed.\",\n \"attachments\": null,\n \"status\": \"queued\",\n \"provider_message_id\": null,\n \"sent_at\": null,\n \"delivered_at\": null,\n \"read_at\": null,\n \"error\": null,\n \"user_id\": 7,\n \"created_at\": \"2026-06-05T13:42:00+00:00\"\n }\n}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\":\"Channel no es una opci\u00f3n v\u00e1lida.\",\"errors\":{\"channel\":[\"Channel no es una opci\u00f3n v\u00e1lida.\"]}}", "name": "A channel that does not exist" }, { "header": [], "code": 422, "body": "{\"message\":\"Falta body.\",\"errors\":{\"body\":[\"Falta body.\"]}}", "name": "Nothing to send" }, { "header": [], "code": 422, "body": "{\"message\":\"El contacto tiene activado No molestar para este canal.\",\"errors\":{\"channel\":[\"El contacto tiene activado No molestar para este canal.\"]}}", "name": "The person asked not to be reached on this channel" } ] } ] }, { "name": "Message Templates", "description": "\nReusable message bodies with `@{{variable}}` placeholders. Variables are\nauto-detected on save and resolved against contact fields (and custom fields)\nat render time. Templates are scoped per channel and optionally per location.", "item": [ { "name": "List message templates", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/message-templates", "query": [ { "key": "channel", "value": "whatsapp", "description": "Filter by channel. One of `sms`, `email`, `whatsapp`, etc.", "disabled": false }, { "key": "location_id", "value": "1", "description": "Scope to a location.", "disabled": false }, { "key": "category", "value": "appointment-reminders", "description": "Optional grouping label.", "disabled": false }, { "key": "per_page", "value": "20", "description": "Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/message-templates?channel=whatsapp&location_id=1&category=appointment-reminders&per_page=20" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists the message templates of this location, newest first. Filter by\nchannel, location, or category." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":null,\"location_id\":null,\"user_id\":3787,\"name\":\"Template aut adipisci quidem\",\"channel\":\"sms\",\"body\":\"Hi {{contact.first_name}}, thanks for reaching out!\",\"variables\":[\"contact.first_name\"],\"category\":\"general\",\"created_at\":null,\"updated_at\":null},{\"id\":null,\"location_id\":null,\"user_id\":3788,\"name\":\"Template quia officia est\",\"channel\":\"sms\",\"body\":\"Hi {{contact.first_name}}, thanks for reaching out!\",\"variables\":[\"contact.first_name\"],\"category\":\"general\",\"created_at\":null,\"updated_at\":null}],\"links\":{\"first\":\"\\\/?page=1\",\"last\":\"\\\/?page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"links\":[{\"url\":null,\"label\":\"« Previous\",\"page\":null,\"active\":false},{\"url\":\"\\\/?page=1\",\"label\":\"1\",\"page\":1,\"active\":true},{\"url\":null,\"label\":\"Next »\",\"page\":null,\"active\":false}],\"path\":\"\\\/\",\"per_page\":20,\"to\":2,\"total\":2}}", "name": "" } ] }, { "name": "Create a message template", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/message-templates", "query": [], "raw": "{{baseUrl}}\/api\/message-templates" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"location_id\":1,\"name\":\"Appointment reminder\",\"channel\":\"whatsapp\",\"body\":\"Hi @{{first_name}}, your appointment is on @{{appointment_date}}.\",\"category\":\"appointment-reminders\"}" }, "description": "Creates a message template for one channel. On save, `@{{variable}}`\ntokens in `body` are extracted into the `variables`\ncolumn for fast lookup at render time. Re-extraction happens on every update." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"location_id\":null,\"user_id\":3789,\"name\":\"Template et animi quos\",\"channel\":\"sms\",\"body\":\"Hi {{contact.first_name}}, thanks for reaching out!\",\"variables\":[\"contact.first_name\"],\"category\":\"general\",\"created_at\":null,\"updated_at\":null}}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\":\"Channel no es una opci\u00f3n v\u00e1lida.\",\"errors\":{\"channel\":[\"Channel no es una opci\u00f3n v\u00e1lida.\"]}}", "name": "A channel that does not exist" }, { "header": [], "code": 422, "body": "{\"message\":\"Falta body.\",\"errors\":{\"body\":[\"Falta body.\"]}}", "name": "An empty body" } ] }, { "name": "Fetch a message template", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/message-templates\/:messageTemplate_id", "query": [], "raw": "{{baseUrl}}\/api\/message-templates\/:messageTemplate_id", "variable": [ { "id": "messageTemplate_id", "key": "messageTemplate_id", "value": "11", "description": "Template ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns one message template by id, with the `variables` list extracted\nfrom its body. Read that\nlist before rendering: it is the contract of what this template needs, and\nit is derived from the body rather than declared, so it is never out of\ndate.\n\nTo get the finished text for a person, use\n`POST \/api\/message-templates\/{id}\/render` instead of substituting on your\nside \u2014 the CRM knows about custom fields and fallbacks, and your string\nreplace does not." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"location_id\":null,\"user_id\":3790,\"name\":\"Template nostrum qui commodi\",\"channel\":\"sms\",\"body\":\"Hi {{contact.first_name}}, thanks for reaching out!\",\"variables\":[\"contact.first_name\"],\"category\":\"general\",\"created_at\":null,\"updated_at\":null}}", "name": "" }, { "header": [], "code": 404, "body": "{\"message\":\"No query results for model.\"}", "name": "Does not exist, or belongs to another location" } ] }, { "name": "Delete a message template", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/message-templates\/:messageTemplate_id", "query": [], "raw": "{{baseUrl}}\/api\/message-templates\/:messageTemplate_id", "variable": [ { "id": "messageTemplate_id", "key": "messageTemplate_id", "value": "11", "description": "Template ID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Deletes a message template by id, so it stops being offered when composing.\nMessages already sent from it are\nuntouched \u2014 they\nwere rendered to plain text at send time and do not reference it." }, "response": [ { "header": [], "code": 200, "body": "{ \"message\": \"Template deleted.\" }", "name": "" } ] }, { "name": "Render template against a contact", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/message-templates\/:messageTemplate_id\/render", "query": [], "raw": "{{baseUrl}}\/api\/message-templates\/:messageTemplate_id\/render", "variable": [ { "id": "messageTemplate_id", "key": "messageTemplate_id", "value": "11", "description": "Template ID." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"contact_id\":42}" }, "description": "Returns the template body with `@{{variable}}` placeholders replaced by the\ncontact's matching fields. `missing` lists variables that could not be\nresolved (useful for UI hints before sending)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"rendered\": \"Hi Ada, your appointment is on 2026-06-08.\",\n \"missing\": [],\n \"channel\": \"whatsapp\"\n}", "name": "" }, { "header": [], "code": 200, "body": "{\n \"rendered\": \"Hi Ada, your appointment is on @{{appointment_date}}.\",\n \"missing\": [\"appointment_date\"],\n \"channel\": \"whatsapp\"\n}", "name": "unresolved variables" } ] } ] }, { "name": "Channel Integrations", "description": "\nPer-location credentials for outbound channels (WhatsApp, Facebook Messenger,\nInstagram DM, Google My Business). Credentials are encrypted at rest. The\nOAuth callback endpoint that exchanges authorization codes for tokens is\nintentionally excluded from public docs (internal redirect target).", "item": [ { "name": "List channel integrations", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/channel-integrations", "query": [ { "key": "location_id", "value": "1", "description": "Scope to a location.", "disabled": false }, { "key": "channel", "value": "whatsapp", "description": "Filter by channel. One of `whatsapp`, `messenger`, `instagram`, `gmb`.", "disabled": false }, { "key": "status", "value": "active", "description": "Filter by status (e.g. `active`, `disconnected`, `expired`).", "disabled": false }, { "key": "per_page", "value": "20", "description": "Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/channel-integrations?location_id=1&channel=whatsapp&status=active&per_page=20" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists the channel integrations of this location \u2014 WhatsApp, email, SMS \u2014\nnewest first. Filter by location, channel, or status." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":null,\"location_id\":null,\"channel\":\"whatsapp\",\"status\":\"connected\",\"metadata\":{\"account_id\":\"acct_g2gh67JMFZ\"},\"connected_at\":\"2026-08-26T02:19:50+00:00\",\"disconnected_at\":null,\"expires_at\":\"2026-08-26T04:19:50+00:00\",\"created_at\":null},{\"id\":null,\"location_id\":null,\"channel\":\"whatsapp\",\"status\":\"connected\",\"metadata\":{\"account_id\":\"acct_ElVYf4Z2Vn\"},\"connected_at\":\"2026-08-26T02:19:50+00:00\",\"disconnected_at\":null,\"expires_at\":\"2026-08-26T04:19:50+00:00\",\"created_at\":null}],\"links\":{\"first\":\"\\\/?page=1\",\"last\":\"\\\/?page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"links\":[{\"url\":null,\"label\":\"« Previous\",\"page\":null,\"active\":false},{\"url\":\"\\\/?page=1\",\"label\":\"1\",\"page\":1,\"active\":true},{\"url\":null,\"label\":\"Next »\",\"page\":null,\"active\":false}],\"path\":\"\\\/\",\"per_page\":20,\"to\":2,\"total\":2}}", "name": "" } ] }, { "name": "Connect a channel integration", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/channel-integrations", "query": [], "raw": "{{baseUrl}}\/api\/channel-integrations" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"channel\":\"whatsapp\",\"location_id\":1,\"credentials\":{\"access_token\":\"architecto\",\"refresh_token\":\"architecto\"},\"metadata\":[],\"expires_in\":3600}" }, "description": "Stores encrypted credentials and marks the integration `active`. For OAuth\nflows, prefer letting the user complete the in-product OAuth dance; use\nthis endpoint when you already have tokens (e.g. via your own OAuth client).\n\nOnly locations you belong to are accepted; omit `location_id` to use your\ncurrent one. WhatsApp is additionally capped at the account's maximum\nnumber of linked numbers (10 by default)." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"location_id\":null,\"channel\":\"whatsapp\",\"status\":\"connected\",\"metadata\":{\"account_id\":\"acct_ZmVG5xkxyX\"},\"connected_at\":\"2026-08-26T02:19:50+00:00\",\"disconnected_at\":null,\"expires_at\":\"2026-08-26T04:19:50+00:00\",\"created_at\":null}}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\":\"Channel no es una opci\u00f3n v\u00e1lida.\",\"errors\":{\"channel\":[\"Channel no es una opci\u00f3n v\u00e1lida.\"]}}", "name": "A channel that does not exist" }, { "header": [], "code": 422, "body": "{\"message\":\"Falta credentials.access_token.\",\"errors\":{\"credentials.access_token\":[\"Falta credentials.access_token.\"]}}", "name": "No credentials" }, { "header": [], "code": 422, "body": "{\"message\":\"Location id no es v\u00e1lido.\",\"errors\":{\"location_id\":[\"Location id no es v\u00e1lido.\"]}}", "name": "A location you do not belong to" } ] }, { "name": "Fetch a channel integration", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/channel-integrations\/:channelIntegration_id", "query": [], "raw": "{{baseUrl}}\/api\/channel-integrations\/:channelIntegration_id", "variable": [ { "id": "channelIntegration_id", "key": "channelIntegration_id", "value": "4", "description": "Integration ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns one channel integration by id. Credentials come back in\nencrypted\/redacted form; only metadata and\nstatus are usable client-side." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"location_id\":null,\"channel\":\"whatsapp\",\"status\":\"connected\",\"metadata\":{\"account_id\":\"acct_yB1hXM3BMo\"},\"connected_at\":\"2026-08-26T02:19:50+00:00\",\"disconnected_at\":null,\"expires_at\":\"2026-08-26T04:19:50+00:00\",\"created_at\":null}}", "name": "" }, { "header": [], "code": 404, "body": "{\"message\":\"No query results for model.\"}", "name": "Does not exist, or belongs to another location" } ] }, { "name": "Refresh integration tokens", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/channel-integrations\/:channelIntegration_id\/refresh", "query": [], "raw": "{{baseUrl}}\/api\/channel-integrations\/:channelIntegration_id\/refresh", "variable": [ { "id": "channelIntegration_id", "key": "channelIntegration_id", "value": "4", "description": "Integration ID." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Exchanges the stored refresh token for a new access token at the provider.\nUpdates `expires_at` and `status`. Returns 502 with the provider's error\nmessage when the refresh call fails (typically expired refresh token \u2014\nthe user must re-OAuth in product)." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"location_id\":null,\"channel\":\"whatsapp\",\"status\":\"connected\",\"metadata\":{\"account_id\":\"acct_sKkxJlPy6M\"},\"connected_at\":\"2026-08-26T02:19:50+00:00\",\"disconnected_at\":null,\"expires_at\":\"2026-08-26T04:19:50+00:00\",\"created_at\":null}}", "name": "" }, { "header": [], "code": 502, "body": "{\n \"message\": \"Refresh token rejected by provider\"\n}", "name": "refresh failed" } ] }, { "name": "Disconnect a channel integration", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/channel-integrations\/:channelIntegration_id", "query": [], "raw": "{{baseUrl}}\/api\/channel-integrations\/:channelIntegration_id", "variable": [ { "id": "channelIntegration_id", "key": "channelIntegration_id", "value": "4", "description": "Integration ID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Marks the integration `disconnected` and clears stored credentials. Existing\nconversations remain readable; outbound messages on this channel will fail\nuntil reconnected." }, "response": [ { "header": [], "code": 200, "body": "{ \"message\": \"Channel integration disconnected.\" }", "name": "" } ] } ] }, { "name": "Negocios y Cotizaciones", "description": "\nThe customer as a legal entity (D2): the thing a quote is actually addressed\nto, with its RFC and its fiscal details. Not to be confused with the\n`CompanyProfile`, which is the CRM owner's own branding.\n\n`external_ref` is the bridge to your system \u2014 set it once and every later\ncall can find the company by your identifier instead of ours.", "item": [ { "name": "List companies", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/companies", "query": [ { "key": "search", "value": "ADPA", "description": "Free text over name, legal name and RFC.", "disabled": false }, { "key": "external_ref", "value": "verificamex-99", "description": "Find the one carrying your identifier.", "disabled": false }, { "key": "per_page", "value": "50", "description": "Rows per page. Default 50, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/companies?search=ADPA&external_ref=verificamex-99&per_page=50" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists the companies of the location the API token belongs to." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":null,\"ulid\":null,\"name\":\"Price Ltd\",\"legal_name\":null,\"tax_id\":null,\"tax_regime\":null,\"cfdi_use\":null,\"address\":null,\"email\":\"contacto@cronin.example\",\"phone\":null,\"website\":null,\"industry\":null,\"owner_id\":null,\"external_ref\":null,\"notes\":null,\"created_at\":null,\"updated_at\":null},{\"id\":null,\"ulid\":null,\"name\":\"Hauck-Leuschke\",\"legal_name\":null,\"tax_id\":null,\"tax_regime\":null,\"cfdi_use\":null,\"address\":null,\"email\":\"contacto@baumbach.example\",\"phone\":null,\"website\":null,\"industry\":null,\"owner_id\":null,\"external_ref\":null,\"notes\":null,\"created_at\":null,\"updated_at\":null}]}", "name": "" } ] }, { "name": "Create a company", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/companies", "query": [], "raw": "{{baseUrl}}\/api\/v1\/companies" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"ADPA\",\"legal_name\":\"ADPA, S.A. de C.V.\",\"tax_id\":\"ADP010101AB1\",\"tax_regime\":\"601\",\"cfdi_use\":\"G03\",\"email\":\"contacto@example.com\",\"phone\":\"+525555555555\",\"external_ref\":\"verificamex-99\"}" }, "description": "Creates a company in this location. A company is the fiscal counterpart of\na deal: who the\ninvoice is made out\nto. Create it when you are about to quote somebody who buys as a business,\nnot for every contact \u2014 a person who buys as a person needs no company.\n\nPut your own identifier in `external_ref` and you never have to store\nours. It is unique inside the location, so a retry that sends the same\none gets a `422` rather than a second row." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"ulid\":null,\"name\":\"Price Ltd\",\"legal_name\":null,\"tax_id\":null,\"tax_regime\":null,\"cfdi_use\":null,\"address\":null,\"email\":\"contacto@dare.example\",\"phone\":null,\"website\":null,\"industry\":null,\"owner_id\":null,\"external_ref\":null,\"notes\":null,\"created_at\":null,\"updated_at\":null}}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\":\"Falta el nombre.\",\"errors\":{\"name\":[\"Falta el nombre.\"]}}", "name": "No name" }, { "header": [], "code": 422, "body": "{\"message\":\"El valor de tax id ya est\u00e1 en uso.\",\"errors\":{\"tax_id\":[\"El valor de tax id ya est\u00e1 en uso.\"]}}", "name": "An RFC already registered here" }, { "header": [], "code": 422, "body": "{\"message\":\"El valor de external ref ya est\u00e1 en uso.\",\"errors\":{\"external_ref\":[\"El valor de external ref ya est\u00e1 en uso.\"]}}", "name": "An external_ref already used" } ] }, { "name": "Fetch a company", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/companies\/:ulid", "query": [], "raw": "{{baseUrl}}\/api\/v1\/companies\/:ulid", "variable": [ { "id": "ulid", "key": "ulid", "value": "01JZ8Z0ZP0000000000000000", "description": "Company ULID (a numeric id still resolves)." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns one company by its ULID, with everything on file plus\n`contacts_count` and `deals_count`, which is\nusually what you actually wanted: whether this company is worth a call.\n\nA company from another location answers `404`, never `403` \u2014 telling an\noutsider \"that exists but is not yours\" is telling them it exists." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"ulid\":null,\"name\":\"Price Ltd\",\"legal_name\":null,\"tax_id\":null,\"tax_regime\":null,\"cfdi_use\":null,\"address\":null,\"email\":\"contacto@hauck.example\",\"phone\":null,\"website\":null,\"industry\":null,\"owner_id\":null,\"external_ref\":null,\"notes\":null,\"created_at\":null,\"updated_at\":null}}", "name": "" } ] }, { "name": "Update a company", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/companies\/:ulid", "query": [], "raw": "{{baseUrl}}\/api\/v1\/companies\/:ulid", "variable": [ { "id": "ulid", "key": "ulid", "value": "01JZ8Z0ZP0000000000000000", "description": "Company ULID." } ] }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Updates a company by its ULID, changing only the fields you send.\nFields you leave out are left alone, so this is\nsafe to call from a sync that only knows about the tax data.\n\nUse it to fill in fiscal details a seller could not collect at the time \u2014\nan RFC that arrives with the purchase order, a CFDI use the accountant\ncorrects. Changing `name` here does not rename anything else: deals and\nquotes already issued keep the name they were issued with." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"ulid\":null,\"name\":\"Price Ltd\",\"legal_name\":null,\"tax_id\":null,\"tax_regime\":null,\"cfdi_use\":null,\"address\":null,\"email\":\"contacto@leuschke.example\",\"phone\":null,\"website\":null,\"industry\":null,\"owner_id\":null,\"external_ref\":null,\"notes\":null,\"created_at\":null,\"updated_at\":null}}", "name": "" } ] }, { "name": "List deals", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/deals", "query": [ { "key": "status", "value": "open", "description": "One of `open`, `won`, `lost`.", "disabled": false }, { "key": "company_id", "value": "12", "description": "Only this company's deals.", "disabled": false }, { "key": "external_ref", "value": "sub_88213", "description": "Find the one carrying your identifier.", "disabled": false }, { "key": "per_page", "value": "50", "description": "Rows per page. Default 50, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/deals?status=open&company_id=12&external_ref=sub_88213&per_page=50" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists the deals of this location, newest first. Use it to reconcile:\nask for `?external_ref=` to find the one carrying your identifier, or for\n`?status=open` to see what is still in play before you close something on\nyour side.\n\n**What you see depends on the token.** A token belonging to somebody who\nmanages the location sees every deal; a seller's token sees only their\nown. That is not a filter you can turn off, so a partial list is not a\nbug \u2014 it is whose token you are using." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"ulid\":\"01KYDKV7N1RMWVK8H79M9H20V1\",\"title\":\"ADPA \\u2014 Paquete 1,100 firmas\",\"description\":null,\"status\":\"open\",\"status_label\":\"Abierto\",\"amount\":{\"amount\":250140000,\"currency\":\"MXN\",\"decimal\":\"25014.0000\",\"formatted\":\"$25,014.00\"},\"paid\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"balance\":{\"amount\":250140000,\"currency\":\"MXN\",\"decimal\":\"25014.0000\",\"formatted\":\"$25,014.00\"},\"weighted_amount\":{\"amount\":100056000,\"currency\":\"MXN\",\"decimal\":\"10005.6000\",\"formatted\":\"$10,005.60\"},\"currency\":\"MXN\",\"pipeline_id\":1,\"pipeline_stage_id\":2,\"stage\":{\"id\":2,\"name\":\"Cotizaci\\u00f3n enviada\",\"probability\":40,\"is_won\":false,\"is_lost\":false},\"company_id\":1,\"primary_contact_id\":null,\"owner_id\":26,\"expected_close_date\":null,\"closed_at\":null,\"lost_reason\":null,\"source\":null,\"attribution\":null,\"external_ref\":null,\"created_at\":\"2026-07-25T03:58:03+00:00\",\"updated_at\":\"2026-07-25T03:58:03+00:00\"},{\"id\":1,\"ulid\":\"01KYDKV7N1RMWVK8H79M9H20V1\",\"title\":\"ADPA \\u2014 Paquete 1,100 firmas\",\"description\":null,\"status\":\"open\",\"status_label\":\"Abierto\",\"amount\":{\"amount\":250140000,\"currency\":\"MXN\",\"decimal\":\"25014.0000\",\"formatted\":\"$25,014.00\"},\"paid\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"balance\":{\"amount\":250140000,\"currency\":\"MXN\",\"decimal\":\"25014.0000\",\"formatted\":\"$25,014.00\"},\"weighted_amount\":{\"amount\":100056000,\"currency\":\"MXN\",\"decimal\":\"10005.6000\",\"formatted\":\"$10,005.60\"},\"currency\":\"MXN\",\"pipeline_id\":1,\"pipeline_stage_id\":2,\"stage\":{\"id\":2,\"name\":\"Cotizaci\\u00f3n enviada\",\"probability\":40,\"is_won\":false,\"is_lost\":false},\"company_id\":1,\"primary_contact_id\":null,\"owner_id\":26,\"expected_close_date\":null,\"closed_at\":null,\"lost_reason\":null,\"source\":null,\"attribution\":null,\"external_ref\":null,\"created_at\":\"2026-07-25T03:58:03+00:00\",\"updated_at\":\"2026-07-25T03:58:03+00:00\"}]}", "name": "" } ] }, { "name": "Create a deal", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/deals", "query": [], "raw": "{{baseUrl}}\/api\/v1\/deals" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"title\":\"ADPA \u2014 Paquete 1,100 firmas\",\"description\":\"Et animi quos velit et fugiat.\",\"company_id\":12,\"primary_contact_id\":340,\"owner_id\":4,\"pipeline_id\":1,\"expected_close_date\":\"2026-08-30\",\"source\":\"verificamex\",\"external_ref\":\"sub_88213\"}" }, "description": "Creates a deal \u2014 an opportunity \u2014 in the location's default pipeline\nunless another is\nnamed. The attribution of its contact is frozen onto it at this moment and\nnever recalculated (D17)." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":1,\"ulid\":\"01KYDKV7N1RMWVK8H79M9H20V1\",\"title\":\"ADPA \\u2014 Paquete 1,100 firmas\",\"description\":null,\"status\":\"open\",\"status_label\":\"Abierto\",\"amount\":{\"amount\":250140000,\"currency\":\"MXN\",\"decimal\":\"25014.0000\",\"formatted\":\"$25,014.00\"},\"paid\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"balance\":{\"amount\":250140000,\"currency\":\"MXN\",\"decimal\":\"25014.0000\",\"formatted\":\"$25,014.00\"},\"weighted_amount\":{\"amount\":100056000,\"currency\":\"MXN\",\"decimal\":\"10005.6000\",\"formatted\":\"$10,005.60\"},\"currency\":\"MXN\",\"pipeline_id\":1,\"pipeline_stage_id\":2,\"stage\":{\"id\":2,\"name\":\"Cotizaci\\u00f3n enviada\",\"probability\":40,\"is_won\":false,\"is_lost\":false},\"company_id\":1,\"primary_contact_id\":null,\"owner_id\":26,\"expected_close_date\":null,\"closed_at\":null,\"lost_reason\":null,\"source\":null,\"attribution\":null,\"external_ref\":null,\"created_at\":\"2026-07-25T03:58:03+00:00\",\"updated_at\":\"2026-07-25T03:58:03+00:00\"}}", "name": "" } ] }, { "name": "Reconcile a deal", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/deals\/reconcile", "query": [], "raw": "{{baseUrl}}\/api\/v1\/deals\/reconcile" }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "required A unique value per operation. A retry with the same key returns the first answer instead of doing the work again. Example: rec-2026-08-02-88213" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"external_ref\":\"sub_88213\",\"status\":\"won\",\"lost_reason\":\"Se fue con la competencia\",\"accepted_quote_ids\":[15],\"amount\":\"25013.94\",\"paid_at\":\"2026-08-02\",\"reference\":\"SPEI-8891\",\"payment_external_ref\":\"charge_9912\"}" }, "description": "Finds the deal by your identifier and closes it. If you did not put an\n`external_ref` on the deal, the company's is used instead \u2014 provided that\ncompany has exactly one open deal, because guessing which of three deals\na payment belongs to is not a guess anybody should make." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": {\"status\": \"won\"}, \"meta\": {\"reconciled\": true, \"payment_recorded\": true}}", "name": "Reconciled" }, { "header": [], "code": 404, "body": "{\"message\": \"No hay ning\u00fan negocio con ese external_ref.\"}", "name": "Nothing to reconcile" }, { "header": [], "code": 409, "body": "{\"message\": \"El negocio ya est\u00e1 cerrado\u2026\", \"data\": {\"status\": \"won\"}}", "name": "Already decided here" } ] }, { "name": "Link a deal to your identifier", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/deals\/:deal_ulid\/external-ref", "query": [], "raw": "{{baseUrl}}\/api\/v1\/deals\/:deal_ulid\/external-ref", "variable": [ { "id": "deal_ulid", "key": "deal_ulid", "value": "01JZ8Z0ZP0000000000000000", "description": "Deal ULID." } ] }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "required A unique value per operation. Example: link-88213" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"external_ref\":\"sub_88213\"}" }, "description": "Attaches your own identifier to a deal that already exists \u2014 for the ones\nthat predate the integration. One deal,\none `external_ref`, unique inside the location." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":1,\"ulid\":\"01KYDKV7N1RMWVK8H79M9H20V1\",\"title\":\"ADPA \\u2014 Paquete 1,100 firmas\",\"description\":null,\"status\":\"open\",\"status_label\":\"Abierto\",\"amount\":{\"amount\":250140000,\"currency\":\"MXN\",\"decimal\":\"25014.0000\",\"formatted\":\"$25,014.00\"},\"paid\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"balance\":{\"amount\":250140000,\"currency\":\"MXN\",\"decimal\":\"25014.0000\",\"formatted\":\"$25,014.00\"},\"weighted_amount\":{\"amount\":100056000,\"currency\":\"MXN\",\"decimal\":\"10005.6000\",\"formatted\":\"$10,005.60\"},\"currency\":\"MXN\",\"pipeline_id\":1,\"pipeline_stage_id\":2,\"stage\":{\"id\":2,\"name\":\"Cotizaci\\u00f3n enviada\",\"probability\":40,\"is_won\":false,\"is_lost\":false},\"company_id\":1,\"primary_contact_id\":null,\"owner_id\":26,\"expected_close_date\":null,\"closed_at\":null,\"lost_reason\":null,\"source\":null,\"attribution\":null,\"external_ref\":null,\"created_at\":\"2026-07-25T03:58:03+00:00\",\"updated_at\":\"2026-07-25T03:58:03+00:00\"}}", "name": "" } ] }, { "name": "Fetch a deal", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/deals\/:ulid", "query": [], "raw": "{{baseUrl}}\/api\/v1\/deals\/:ulid", "variable": [ { "id": "ulid", "key": "ulid", "value": "01JZ8Z0ZP0000000000000000", "description": "Deal ULID (a numeric id still resolves)." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns one deal by its ULID, with its stage and its company. Read `status` before you act on\nit: a deal a person here already closed is never flipped by the API, and\nthis is where you find out that happened." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":1,\"ulid\":\"01KYDKV7N1RMWVK8H79M9H20V1\",\"title\":\"ADPA \\u2014 Paquete 1,100 firmas\",\"description\":null,\"status\":\"open\",\"status_label\":\"Abierto\",\"amount\":{\"amount\":250140000,\"currency\":\"MXN\",\"decimal\":\"25014.0000\",\"formatted\":\"$25,014.00\"},\"paid\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"balance\":{\"amount\":250140000,\"currency\":\"MXN\",\"decimal\":\"25014.0000\",\"formatted\":\"$25,014.00\"},\"weighted_amount\":{\"amount\":100056000,\"currency\":\"MXN\",\"decimal\":\"10005.6000\",\"formatted\":\"$10,005.60\"},\"currency\":\"MXN\",\"pipeline_id\":1,\"pipeline_stage_id\":2,\"stage\":{\"id\":2,\"name\":\"Cotizaci\\u00f3n enviada\",\"probability\":40,\"is_won\":false,\"is_lost\":false},\"company_id\":1,\"primary_contact_id\":null,\"owner_id\":26,\"expected_close_date\":null,\"closed_at\":null,\"lost_reason\":null,\"source\":null,\"attribution\":null,\"external_ref\":null,\"created_at\":\"2026-07-25T03:58:03+00:00\",\"updated_at\":\"2026-07-25T03:58:03+00:00\"}}", "name": "" } ] }, { "name": "List quotes", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/quotes", "query": [ { "key": "deal_id", "value": "7", "description": "Only this deal's quotes.", "disabled": false }, { "key": "status", "value": "shared", "description": "One of `draft`, `shared`, `viewed`, `accepted`, `rejected`, `withdrawn`, `expired`, `superseded`.", "disabled": false }, { "key": "folio", "value": "COT-7K3M9", "description": "The dictated code, with or without prefix or dash.", "disabled": false }, { "key": "per_page", "value": "50", "description": "Rows per page. Default 50, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/quotes?deal_id=7&status=shared&folio=COT-7K3M9&per_page=50" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists the quotes issued in this location, newest first. Filter by\n`deal_id` to see the\noptions offered on one opportunity, or by `folio` to look up the code a\ncustomer read out on the phone \u2014 with or without its prefix and dash,\nbecause nobody dictates punctuation.\n\nA draft has no folio yet: the code is assigned when the quote is shared,\nwhich is also the moment its contents are frozen." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"ulid\":\"01KYDKV7P4RVYJZZ6JNAJ521YR\",\"deal_id\":15,\"company_id\":null,\"contact_id\":6295,\"owner_id\":26,\"quote_template_id\":null,\"folio\":null,\"reference\":\"Borrador\",\"version\":1,\"title\":\"Patito\",\"intro\":null,\"status\":\"draft\",\"status_label\":\"Borrador\",\"is_option\":false,\"currency\":\"MXN\",\"subtotal\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"discount_total\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"tax_total\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"total\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"valid_until\":\"2026-08-09\",\"shared_at\":null,\"decided_at\":null,\"snapshot_hash\":null,\"external_ref\":null,\"pdf_url\":\"http:\\\/\\\/klozzo.com\\\/api\\\/v1\\\/quotes\\\/01KYDKV7P4RVYJZZ6JNAJ521YR\\\/pdf\\\/signed?893456000&signature=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2\",\"created_at\":\"2026-07-25T18:11:14+00:00\",\"updated_at\":\"2026-07-25T18:11:14+00:00\"},{\"id\":1,\"ulid\":\"01KYDKV7P4RVYJZZ6JNAJ521YR\",\"deal_id\":15,\"company_id\":null,\"contact_id\":6295,\"owner_id\":26,\"quote_template_id\":null,\"folio\":null,\"reference\":\"Borrador\",\"version\":1,\"title\":\"Patito\",\"intro\":null,\"status\":\"draft\",\"status_label\":\"Borrador\",\"is_option\":false,\"currency\":\"MXN\",\"subtotal\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"discount_total\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"tax_total\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"total\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"valid_until\":\"2026-08-09\",\"shared_at\":null,\"decided_at\":null,\"snapshot_hash\":null,\"external_ref\":null,\"pdf_url\":\"http:\\\/\\\/klozzo.com\\\/api\\\/v1\\\/quotes\\\/01KYDKV7P4RVYJZZ6JNAJ521YR\\\/pdf\\\/signed?893456000&signature=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2\",\"created_at\":\"2026-07-25T18:11:14+00:00\",\"updated_at\":\"2026-07-25T18:11:14+00:00\"}]}", "name": "" } ] }, { "name": "Create a quote", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/quotes", "query": [], "raw": "{{baseUrl}}\/api\/v1\/quotes" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"deal_id\":7,\"title\":\"Firmado Electr\u00f3nico\",\"valid_until\":\"2026-08-14\",\"is_option\":false,\"company_id\":12,\"contact_id\":340,\"quote_template_id\":3,\"items\":[{\"name\":\"Costo de las firmas por volumen\",\"quantity\":\"1100\",\"unit_price\":\"19.6034\",\"unit_label\":\"firma\",\"tax_rate_id\":1,\"discount_percent\":\"0\",\"is_informational\":false}]}" }, "description": "Creates a quote as a **draft** on an existing deal, with its lines. A\ndraft burns no\nfolio and is not visible to the customer: sharing it is a separate,\ndeliberate act that freezes the document (D24)." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":1,\"ulid\":\"01KYDKV7P4RVYJZZ6JNAJ521YR\",\"deal_id\":15,\"company_id\":null,\"contact_id\":6295,\"owner_id\":26,\"quote_template_id\":null,\"folio\":null,\"reference\":\"Borrador\",\"version\":1,\"title\":\"Patito\",\"intro\":null,\"status\":\"draft\",\"status_label\":\"Borrador\",\"is_option\":false,\"currency\":\"MXN\",\"subtotal\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"discount_total\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"tax_total\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"total\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"valid_until\":\"2026-08-09\",\"shared_at\":null,\"decided_at\":null,\"snapshot_hash\":null,\"external_ref\":null,\"pdf_url\":\"http:\\\/\\\/klozzo.com\\\/api\\\/v1\\\/quotes\\\/01KYDKV7P4RVYJZZ6JNAJ521YR\\\/pdf\\\/signed?893456000&signature=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2\",\"created_at\":\"2026-07-25T18:11:14+00:00\",\"updated_at\":\"2026-07-25T18:11:14+00:00\"}}", "name": "" } ] }, { "name": "Fetch a quote", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/quotes\/:ulid", "query": [], "raw": "{{baseUrl}}\/api\/v1\/quotes\/:ulid", "variable": [ { "id": "ulid", "key": "ulid", "value": "01JZ8Z0ZP0000000000000000", "description": "Quote ULID (a numeric id still resolves)." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns one quote by its ULID, with its line items and its totals. Money always comes back as\nan object \u2014 `amount` is an integer at scale 10\u2074, `decimal` is the exact\nstring, `formatted` is for display. Never parse `formatted`.\n\n`pdf_url` is a short-lived signed link you can put straight into your own\ninterface without proxying a token through a browser. It is **not** the\ncustomer's link: that one carries the commercial validity and the read\ntracking behind it." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":1,\"ulid\":\"01KYDKV7P4RVYJZZ6JNAJ521YR\",\"deal_id\":15,\"company_id\":null,\"contact_id\":6295,\"owner_id\":26,\"quote_template_id\":null,\"folio\":null,\"reference\":\"Borrador\",\"version\":1,\"title\":\"Patito\",\"intro\":null,\"status\":\"draft\",\"status_label\":\"Borrador\",\"is_option\":false,\"currency\":\"MXN\",\"subtotal\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"discount_total\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"tax_total\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"total\":{\"amount\":0,\"currency\":\"MXN\",\"decimal\":\"0.0000\",\"formatted\":\"$0.00\"},\"valid_until\":\"2026-08-09\",\"shared_at\":null,\"decided_at\":null,\"snapshot_hash\":null,\"external_ref\":null,\"pdf_url\":\"http:\\\/\\\/klozzo.com\\\/api\\\/v1\\\/quotes\\\/01KYDKV7P4RVYJZZ6JNAJ521YR\\\/pdf\\\/signed?893456000&signature=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2\",\"created_at\":\"2026-07-25T18:11:14+00:00\",\"updated_at\":\"2026-07-25T18:11:14+00:00\"}}", "name": "" } ] }, { "name": "Download the quote PDF", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/quotes\/:quote_ulid\/pdf", "query": [], "raw": "{{baseUrl}}\/api\/v1\/quotes\/:quote_ulid\/pdf", "variable": [ { "id": "quote_ulid", "key": "quote_ulid", "value": "01JZ8Z0ZP0000000000000000", "description": "Quote ULID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the PDF of one quote, rendered from the frozen snapshot (D8), so\nthe same quote produces the\nsame bytes in a year's time. Reachable two ways: with an API token, or\nthrough the short-lived signed `pdf_url` the quote resource hands out \u2014\nwhich is what lets your own UI show the document without proxying a token\nthrough somebody's browser.\n\nThis is **not** the customer's link. That one is a `DocumentLink` with the\ncommercial validity, the branded viewer and read tracking behind it (D13)." }, "response": [ { "header": [], "code": 200, "body": "\"%PDF-1.7 \u2026\"", "name": "PDF" } ] }, { "name": "Record a sale", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/sales", "query": [], "raw": "{{baseUrl}}\/api\/v1\/sales" }, "method": "POST", "header": [ { "key": "Idempotency-Key", "value": "required A unique value per operation. A retry with the same key returns the first answer instead of doing the work again. Example: sale-2026-08-23-88213" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"external_ref\":\"sale_88213\",\"amount\":\"1499.00\",\"currency\":\"MXN\",\"paid_at\":\"2026-08-23T10:00:00Z\",\"method\":\"tarjeta\",\"reference\":\"ch_9912\",\"title\":\"Plan Pro anual\",\"deal_external_ref\":\"sub_44\",\"customer\":{\"email\":\"ada@example.com\",\"phone\":\"+52 55 1234 5678\",\"phone_country\":\"kh\",\"first_name\":\"Ada\",\"last_name\":\"Lovelace\",\"company_name\":\"ADPA\",\"company_external_ref\":\"verificamex-99\"},\"plan\":{\"name\":\"Plan Pro\",\"product_sku\":\"PLAN-PRO\",\"external_ref\":\"sub_88213\",\"starts_at\":\"2026-08-23\",\"ends_at\":\"2027-08-23\",\"term_months\":12,\"auto_renew\":true}}" }, "description": "Records a sale for a purchase that happened entirely on your side, with\nnobody here\nopening a deal for it \u2014 a self-service checkout, a renewal that charged\nitself. Send the money and the customer; the CRM works out what it means\nand tells you which rule fired in `meta.matched_by`.\n\nIt may attach the sale to an open deal the customer already had, or open\none **already won and with no owner** when there is none \u2014 because\nnobody here attended this customer, and giving the commission to whoever\nhappens to be listed would be worse than leaving it unclaimed. When that\nhappens `meta.claimable` is `true` and a seller claims it from the CRM.\n\nTwo open deals for the same customer never resolve to a guess: a new deal\nis opened and the ambiguity is left for a person.\n\nUse `POST \/api\/v1\/deals\/reconcile` instead when the deal already exists\nand you know which one, and `POST \/api\/v1\/payments` for a further\ninstalment of a sale already recorded here." }, "response": [ { "header": [], "code": 200, "body": "{\"meta\": {\"created\": false, \"matched_by\": \"payment_external_ref\"}}", "name": "Already recorded" }, { "header": [], "code": 201, "body": "{\"data\": {\"deal\": {\"status\": \"won\", \"owner_id\": null}}, \"meta\": {\"created\": true, \"deal_created\": true, \"matched_by\": \"created\", \"claimable\": true}}", "name": "Nobody had attended this customer" }, { "header": [], "code": 404, "body": "{\"message\": \"No hay ning\u00fan negocio con el external_ref \u00absub_44\u00bb.\"}", "name": "You named a deal that is not here" } ] }, { "name": "List payments", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/payments", "query": [ { "key": "deal_id", "value": "7", "description": "Only this deal's payments.", "disabled": false }, { "key": "external_ref", "value": "spei-8891", "description": "Find the one carrying your identifier.", "disabled": false }, { "key": "per_page", "value": "50", "description": "Rows per page. Default 50, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/payments?deal_id=7&external_ref=spei-8891&per_page=50" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists the payments recorded in this location, most recent first. Use it to\ncheck what your side has\nalready reported before reporting it again \u2014 `?external_ref=` finds the\none carrying your charge identifier, which is the cheapest way to answer\n\"did that webhook land?\"." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":null,\"deal_id\":null,\"quote_id\":null,\"subscription_id\":null,\"amount\":{\"amount\":100000000,\"currency\":\"MXN\",\"decimal\":\"10000.0000\",\"formatted\":\"$10,000.00\"},\"currency\":\"MXN\",\"paid_at\":\"2026-08-17T02:19:50+00:00\",\"method\":\"transferencia\",\"method_label\":\"Transferencia\",\"origin\":null,\"reference\":\"SPEI-3724\",\"note\":null,\"recorded_by\":null,\"external_ref\":null,\"created_at\":null},{\"id\":null,\"deal_id\":null,\"quote_id\":null,\"subscription_id\":null,\"amount\":{\"amount\":100000000,\"currency\":\"MXN\",\"decimal\":\"10000.0000\",\"formatted\":\"$10,000.00\"},\"currency\":\"MXN\",\"paid_at\":\"2026-08-15T02:19:50+00:00\",\"method\":\"transferencia\",\"method_label\":\"Transferencia\",\"origin\":null,\"reference\":\"SPEI-0432\",\"note\":null,\"recorded_by\":null,\"external_ref\":null,\"created_at\":null}]}", "name": "" } ] }, { "name": "Record a payment", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/payments", "query": [], "raw": "{{baseUrl}}\/api\/v1\/payments" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"deal_id\":7,\"quote_id\":15,\"amount\":\"25013.94\",\"paid_at\":\"2026-08-02\",\"method\":\"transferencia\",\"reference\":\"SPEI-8891\",\"note\":\"Primer parcialidad\",\"external_ref\":\"charge_9912\"}" }, "description": "Records a payment against a deal that already exists. It does not\nclose the deal and it does not accept a quote \u2014 use\n`POST \/api\/v1\/deals\/reconcile` when the payment is what closes the sale,\nor `POST \/api\/v1\/sales` when there was never a deal to begin with.\n\nInstalments are several calls against the same `deal_id`; give each one\nits own `external_ref` so a retry of the second never looks like the\nfirst." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"deal_id\":null,\"quote_id\":null,\"subscription_id\":null,\"amount\":{\"amount\":100000000,\"currency\":\"MXN\",\"decimal\":\"10000.0000\",\"formatted\":\"$10,000.00\"},\"currency\":\"MXN\",\"paid_at\":\"2026-08-12T02:19:50+00:00\",\"method\":\"transferencia\",\"method_label\":\"Transferencia\",\"origin\":null,\"reference\":\"SPEI-0564\",\"note\":null,\"recorded_by\":null,\"external_ref\":null,\"created_at\":null}}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\":\"Deal id no es v\u00e1lido.\",\"errors\":{\"deal_id\":[\"Deal id no es v\u00e1lido.\"]}}", "name": "A deal from another location, or none" }, { "header": [], "code": 422, "body": "{\"message\":\"Amount no es un importe v\u00e1lido.\",\"errors\":{\"amount\":[\"Amount no es un importe v\u00e1lido.\"]}}", "name": "An amount that is not a number" } ] } ] }, { "name": "Documents", "description": "\nRead tracking for a document you shared with somebody. There is one public\nendpoint and it is called by the viewer itself, not by an integrator: what it\nis for is knowing that the customer opened the quote three times and never\ncalled back.\n\nReceives the public viewer's read-tracking heartbeats (T4-1). Time is\naggregated live onto the ViewSession and its pages \u2014 there is no raw\nheartbeat table (D12). A hidden\/idle tab reports `visible=false` and adds\nnothing, which is what kills email-scanner \"opens\" (D12\/R1).", "item": [ { "name": "Report reading time on a shared document", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/documents\/heartbeat", "query": [], "raw": "{{baseUrl}}\/api\/documents\/heartbeat" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"session_token\":\"01JAX2Q7K6MPQ4S5V8W9YZBCDE\",\"page_number\":3,\"visible\":true}" }, "description": "Records that a document is still open. Called by the public document viewer\nevery few seconds while somebody has\nthe document open, so the sender can see how long each page was actually\nread. Send `visible: false` when the tab is hidden and the beat counts as\nzero \u2014 that is what stops an email scanner from looking like a reader.\n\nPublic on purpose: the reader has no account. What identifies the session\nis `session_token`, handed out by the viewer itself when the link opens.\nAn unknown token gets a `404` and nothing is recorded.", "auth": { "type": "noauth" } }, "response": [ { "header": [], "code": 200, "body": "{\"ok\": true, \"is_valid\": true, \"is_completed\": false}", "name": "" }, { "header": [], "code": 404, "body": "{\"ok\": false}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\": \"The session token field is required.\", \"errors\": {\"session_token\": [\"The session token field is required.\"]}}", "name": "" } ] } ] }, { "name": "Imports", "description": "\nBulk-load contacts, leads, or companies from CSV\/XLSX files. The flow is\nasynchronous: `store` enqueues a `ProcessImport` job and returns immediately\nwith status `pending`. Poll `status` for progress; fetch the error CSV via\n`downloadErrors` once finished.", "item": [ { "name": "List imports", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/imports", "query": [ { "key": "per_page", "value": "20", "description": "Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/imports?per_page=20" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns paginated import jobs owned by the authenticated user, newest first." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":null,\"type\":\"contacts\",\"file_name\":\"adipisci.csv\",\"status\":\"pending\",\"total_rows\":0,\"processed_rows\":0,\"succeeded_rows\":null,\"failed_rows\":0,\"column_mapping\":null,\"duplicate_handling\":\"skip\",\"errors\":null,\"error_file_available\":false,\"progress_percentage\":0,\"started_at\":null,\"finished_at\":null,\"completed_at\":null,\"created_at\":null,\"updated_at\":null},{\"id\":null,\"type\":\"contacts\",\"file_name\":\"fugit.csv\",\"status\":\"pending\",\"total_rows\":0,\"processed_rows\":0,\"succeeded_rows\":null,\"failed_rows\":0,\"column_mapping\":null,\"duplicate_handling\":\"skip\",\"errors\":null,\"error_file_available\":false,\"progress_percentage\":0,\"started_at\":null,\"finished_at\":null,\"completed_at\":null,\"created_at\":null,\"updated_at\":null}],\"links\":{\"first\":\"\\\/?page=1\",\"last\":\"\\\/?page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"links\":[{\"url\":null,\"label\":\"« Previous\",\"page\":null,\"active\":false},{\"url\":\"\\\/?page=1\",\"label\":\"1\",\"page\":1,\"active\":true},{\"url\":null,\"label\":\"Next »\",\"page\":null,\"active\":false}],\"path\":\"\\\/\",\"per_page\":20,\"to\":2,\"total\":2}}", "name": "" } ] }, { "name": "Create an import", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/imports", "query": [], "raw": "{{baseUrl}}\/api\/imports" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "multipart\/form-data" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "formdata", "formdata": [ { "key": "type", "value": "contacts", "type": "text", "description": "What to import. One of `contacts`, `leads`, `companies`." }, { "key": "duplicate_handling", "value": "skip", "type": "text", "description": "Action on collision. One of `skip` (default), `update`, `create`." }, { "key": "location_id", "value": "1", "type": "text", "description": "Scope the import to a specific location." }, { "key": "file", "src": [], "type": "file" } ] }, "description": "Creates an import: uploads a CSV\/XLSX file of contacts and queues it for\nprocessing. Must be sent as\n`multipart\/form-data`. Returns immediately with `status=pending`; poll\n`GET \/api\/imports\/{id}\/status` for progress." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"type\":\"contacts\",\"file_name\":\"eius.csv\",\"status\":\"pending\",\"total_rows\":0,\"processed_rows\":0,\"succeeded_rows\":null,\"failed_rows\":0,\"column_mapping\":null,\"duplicate_handling\":\"skip\",\"errors\":null,\"error_file_available\":false,\"progress_percentage\":0,\"started_at\":null,\"finished_at\":null,\"completed_at\":null,\"created_at\":null,\"updated_at\":null}}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\":\"File debe ser un archivo de tipo: csv, txt, xlsx, xls.\",\"errors\":{\"file\":[\"File debe ser un archivo de tipo: csv, txt, xlsx, xls.\"]}}", "name": "A file type that is not accepted" }, { "header": [], "code": 422, "body": "{\"message\":\"File no puede pesar m\u00e1s de 10240 kilobytes.\",\"errors\":{\"file\":[\"File no puede pesar m\u00e1s de 10240 kilobytes.\"]}}", "name": "Over 10 MB" }, { "header": [], "code": 422, "body": "{\"message\":\"Falta type.\",\"errors\":{\"type\":[\"Falta type.\"]}}", "name": "Nothing to import" } ] }, { "name": "Fetch an import", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/imports\/:id", "query": [], "raw": "{{baseUrl}}\/api\/imports\/:id", "variable": [ { "id": "id", "key": "id", "value": "17", "description": "Import ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns one import by id, with its full payload and the original column\nmapping. For lightweight progress\npolling, prefer `status` instead." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"type\":\"contacts\",\"file_name\":\"adipisci.csv\",\"status\":\"pending\",\"total_rows\":0,\"processed_rows\":0,\"succeeded_rows\":null,\"failed_rows\":0,\"column_mapping\":null,\"duplicate_handling\":\"skip\",\"errors\":null,\"error_file_available\":false,\"progress_percentage\":0,\"started_at\":null,\"finished_at\":null,\"completed_at\":null,\"created_at\":null,\"updated_at\":null}}", "name": "" } ] }, { "name": "Delete an import", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/imports\/:id", "query": [], "raw": "{{baseUrl}}\/api\/imports\/:id", "variable": [ { "id": "id", "key": "id", "value": "17", "description": "Import ID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Removes the import record and original upload from disk. Imported contacts\nare NOT removed." }, "response": [ { "header": [], "code": 200, "body": "{ \"message\": \"Import deleted.\" }", "name": "" } ] }, { "name": "Import progress", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/imports\/:import_id\/status", "query": [], "raw": "{{baseUrl}}\/api\/imports\/:import_id\/status", "variable": [ { "id": "import_id", "key": "import_id", "value": "17", "description": "Import ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the progress of one import in about a kilobyte, meant for polling.\nCall every 2\u20135 s\nuntil `status` is `completed` or `failed`." }, "response": [ { "header": [], "code": 200, "body": "{\n \"id\": 17,\n \"status\": \"processing\",\n \"total_rows\": 1500,\n \"processed_rows\": 420,\n \"succeeded_rows\": 415,\n \"failed_rows\": 5,\n \"progress_percentage\": 28,\n \"errors\": null,\n \"error_file_available\": false,\n \"started_at\": \"2026-06-05T13:42:00+00:00\",\n \"finished_at\": null,\n \"completed_at\": null\n}", "name": "" } ] }, { "name": "Download error CSV", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/imports\/:import_id\/errors", "query": [], "raw": "{{baseUrl}}\/api\/imports\/:import_id\/errors", "variable": [ { "id": "import_id", "key": "import_id", "value": "17", "description": "Import ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Streams a CSV containing the rows that failed validation, with an `error`\ncolumn appended. Available only when `error_file_available=true` in the\nstatus response." }, "response": [ { "header": [], "code": 200, "body": "\"\"", "name": "streamed CSV download" }, { "header": [], "code": 404, "body": "{ \"message\": \"No error file\" }", "name": "no error file" } ] } ] }, { "name": "Exports", "description": "\nGenerate downloadable CSV\/XLSX dumps of contacts. The flow is asynchronous:\n`store` enqueues an `ExportContacts` job and returns immediately. Poll `show`\nuntil `status=completed`, then download via the signed `download` URL.", "item": [ { "name": "List exports", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/exports", "query": [ { "key": "per_page", "value": "20", "description": "Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/exports?per_page=20" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns paginated export jobs owned by the authenticated user, newest first." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":null,\"format\":\"csv\",\"status\":\"pending\",\"total_rows\":0,\"file_name\":null,\"filters\":null,\"columns\":null,\"error\":null,\"started_at\":null,\"finished_at\":null,\"expires_at\":null,\"created_at\":null,\"download_url\":null},{\"id\":null,\"format\":\"csv\",\"status\":\"pending\",\"total_rows\":0,\"file_name\":null,\"filters\":null,\"columns\":null,\"error\":null,\"started_at\":null,\"finished_at\":null,\"expires_at\":null,\"created_at\":null,\"download_url\":null}],\"links\":{\"first\":\"\\\/?page=1\",\"last\":\"\\\/?page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"links\":[{\"url\":null,\"label\":\"« Previous\",\"page\":null,\"active\":false},{\"url\":\"\\\/?page=1\",\"label\":\"1\",\"page\":1,\"active\":true},{\"url\":null,\"label\":\"Next »\",\"page\":null,\"active\":false}],\"path\":\"\\\/\",\"per_page\":20,\"to\":2,\"total\":2}}", "name": "" } ] }, { "name": "Create an export", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/exports", "query": [], "raw": "{{baseUrl}}\/api\/exports" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"format\":\"csv\",\"filters\":[],\"columns\":[\"first_name\",\"last_name\",\"email\"],\"location_id\":1}" }, "description": "Queues an export of contacts and answers immediately with\n`status=pending`. Poll the\nresource (`GET \/api\/exports\/{id}`) until `status=completed`, then call\n`GET \/api\/exports\/{id}\/download` to stream the file." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"format\":\"csv\",\"status\":\"pending\",\"total_rows\":0,\"file_name\":null,\"filters\":null,\"columns\":null,\"error\":null,\"started_at\":null,\"finished_at\":null,\"expires_at\":null,\"created_at\":null,\"download_url\":null}}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\":\"Format no es una opci\u00f3n v\u00e1lida.\",\"errors\":{\"format\":[\"Format no es una opci\u00f3n v\u00e1lida.\"]}}", "name": "A format that does not exist" }, { "header": [], "code": 422, "body": "{\"message\":\"Columns.0 no puede tener m\u00e1s de 64 caracteres.\",\"errors\":{\"columns.0\":[\"Columns.0 no puede tener m\u00e1s de 64 caracteres.\"]}}", "name": "A column that is not a column" } ] }, { "name": "Fetch an export", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/exports\/:id", "query": [], "raw": "{{baseUrl}}\/api\/exports\/:id", "variable": [ { "id": "id", "key": "id", "value": "8", "description": "Export ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the full export record including current `status` and (when ready)\na download URL." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"format\":\"csv\",\"status\":\"pending\",\"total_rows\":0,\"file_name\":null,\"filters\":null,\"columns\":null,\"error\":null,\"started_at\":null,\"finished_at\":null,\"expires_at\":null,\"created_at\":null,\"download_url\":null}}", "name": "" } ] }, { "name": "Delete an export", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/exports\/:id", "query": [], "raw": "{{baseUrl}}\/api\/exports\/:id", "variable": [ { "id": "id", "key": "id", "value": "8", "description": "Export ID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Deletes the export record and the underlying file from storage. Subsequent\ndownload attempts will return 404." }, "response": [ { "header": [], "code": 200, "body": "{ \"message\": \"Export deleted.\" }", "name": "" } ] }, { "name": "Download export file", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/exports\/:export_id\/download", "query": [], "raw": "{{baseUrl}}\/api\/exports\/:export_id\/download", "variable": [ { "id": "export_id", "key": "export_id", "value": "8", "description": "Export ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Streams the finished export file through a pre-signed link that needs no\ntoken. Available only when `status=completed` and the\nfile has not been pruned.\n\n**Do not build this URL yourself.** It is a pre-signed link: take the\n`download_url` the export returns and follow it as-is. It carries no token\n\u2014 the signature is the credential \u2014 which is what lets you hand it to a\nbrowser, a download manager or a colleague without leaking an API key.\nIt stops working on `expires_at`, and a tampered or expired signature\nanswers `403`, not `404`.", "auth": { "type": "noauth" } }, "response": [ { "header": [], "code": 200, "body": "\"\"", "name": "streamed file download" }, { "header": [], "code": 403, "body": "{ \"message\": \"Invalid signature.\" }", "name": "expired or tampered signature" }, { "header": [], "code": 404, "body": "{ \"message\": \"Not Found\" }", "name": "not ready or pruned" } ] } ] }, { "name": "Bulk Operations", "description": "\nAsynchronous batch jobs that act on many contacts at once (tag, untag, delete,\netc.). Differs from `POST \/api\/contacts\/bulk` (synchronous delete-only) in two\nways: this runs in the background on the `bulk` queue, and supports more\nactions with per-row failure tracking.", "item": [ { "name": "Start a bulk operation", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/bulk-operations", "query": [], "raw": "{{baseUrl}}\/api\/bulk-operations" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"action\":\"tag\",\"payload\":{\"ids\":[42,43,44],\"tag_id\":3}}" }, "description": "Enqueues the job and returns 202 with the operation record. Poll\n`GET \/api\/bulk-operations\/{id}` until `status=completed` or `failed`." }, "response": [ { "header": [], "code": 202, "body": "{\n \"id\": 31,\n \"action\": \"tag\",\n \"status\": \"pending\",\n \"total\": 3,\n \"processed\": 0,\n \"failed\": 0,\n \"progress\": 0,\n \"errors\": null,\n \"started_at\": null,\n \"finished_at\": null,\n \"created_at\": \"2026-06-05T13:42:00+00:00\"\n}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\":\"Action no es una opci\u00f3n v\u00e1lida.\",\"errors\":{\"action\":[\"Action no es una opci\u00f3n v\u00e1lida.\"]}}", "name": "An action that does not exist" }, { "header": [], "code": 422, "body": "{\"message\":\"Falta payload.ids.\",\"errors\":{\"payload.ids\":[\"Falta payload.ids.\"]}}", "name": "No targets" } ] }, { "name": "Bulk operation status", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/bulk-operations\/:bulkOperation_id", "query": [], "raw": "{{baseUrl}}\/api\/bulk-operations\/:bulkOperation_id", "variable": [ { "id": "bulkOperation_id", "key": "bulkOperation_id", "value": "31", "description": "Bulk operation ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the current state of a bulk operation. `progress` is `(processed \/\ntotal) * 100` rounded. `errors` is populated per-row when individual rows\nfail (the job continues; only `status=failed` indicates a global failure)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"id\": 31,\n \"action\": \"tag\",\n \"status\": \"processing\",\n \"total\": 3,\n \"processed\": 2,\n \"failed\": 0,\n \"progress\": 66,\n \"errors\": null,\n \"started_at\": \"2026-06-05T13:42:01+00:00\",\n \"finished_at\": null,\n \"created_at\": \"2026-06-05T13:42:00+00:00\"\n}", "name": "" }, { "header": [], "code": 404, "body": "{\"message\":\"No query results for model.\"}", "name": "Does not exist, or belongs to another location" } ] } ] }, { "name": "Pixel \u00b7 server events", "description": "\nReport conversions from your own backend, so the ones an ad blocker eats in\nthe browser still reach Klozzo.\n\nAuthenticate with your site's **secret key** as a Bearer token. It is shown\nonce, when the site is created, and only its hash is stored \u2014 if it is lost\nit can be reissued, never recovered.\n\n> **Send the visitor's `anonymous_id` and everything changes.** The pixel\n> puts it into every form on your site as a hidden `kz_anonymous_id` field,\n> so your backend already receives it with the submission \u2014 store it with the\n> order and send it back here. Without it the event still lands, but as an\n> orphan: a purchase with no browsing behind it, no source, no session,\n> nothing to explain where the customer came from. This is the single most\n> common way a server-side integration ends up worth half of what it could be.", "item": [ { "name": "Report events from a server", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/events", "query": [], "raw": "{{baseUrl}}\/api\/v1\/events" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"anonymous_id\":\"0d5b6b6e-3e1f-4a5e-9a0a-6c4b0e4b1a2c\",\"events\":[{\"event_id\":\"ord_10293\",\"action_source\":\"server\",\"name\":\"purchase\",\"anonymous_id\":\"6b72fe4a-5b40-307c-bc24-f79acf9a1bb9\",\"occurred_at\":\"2026-08-02T18:04:00-06:00\",\"url\":\"https:\\\/\\\/example.com\\\/checkout\\\/gracias\",\"path\":\"\\\/checkout\\\/gracias\",\"value\":1899.5,\"currency\":\"MXN\",\"properties\":{\"order_id\":\"ORD-10293\"},\"traits\":{\"email\":\"ana@tienda.test\"}}]}" }, "description": "Reports events your own server knows about \u2014 a purchase, a refund, a\nrenewal \u2014 up to 500 in one batch. Unlike the browser endpoint, a batch is **not**\nrejected as a whole: the valid events are accepted and the rest are\nreported back with the reason. A backend can act on a partial answer; a\nbrowser cannot, which is why the two behave differently." }, "response": [ { "header": [], "code": 202, "body": "{\"received\": 2, \"rejected\": 1, \"errors\": {\"1\": [\"`purchase` needs a `value`.\"]}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\":\"A Bearer token with your site secret key is required.\"}", "name": "No key, or a key that does not exist" }, { "header": [], "code": 422, "body": "{\"message\":\"Falta events.\",\"errors\":{\"events\":[\"Falta events.\"]}}", "name": "An empty batch" }, { "header": [], "code": 422, "body": "{\"message\":\"Events no puede tener m\u00e1s de 500 elementos.\",\"errors\":{\"events\":[\"Events no puede tener m\u00e1s de 500 elementos.\"]}}", "name": "More than 500 events in one call" }, { "header": [], "code": 429, "body": "{\"message\":\"Too Many Attempts.\"}", "name": "Over the site's budget" } ] } ] }, { "name": "Webhook Endpoints (outbound)", "description": "\nManage destinations that receive event notifications from the CRM. Each\nendpoint subscribes to one or more event names; events are delivered as signed\nHTTPS POST requests (see the **Webhooks & Public Tracking** appendix at the\nbottom of this page for the envelope, signature scheme, and retry policy).\n\nThe `secret` is auto-generated on create and is the HMAC-SHA256 key used to\nsign every delivery. Treat it like a password \u2014 it is returned only on the\ninitial create response and on `show`; rotate by deleting and recreating.", "item": [ { "name": "List webhook endpoints", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/webhook-endpoints", "query": [ { "key": "location_id", "value": "1", "description": "Scope to a location.", "disabled": false }, { "key": "is_active", "value": "1", "description": "Filter active vs disabled.", "disabled": false }, { "key": "per_page", "value": "20", "description": "Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/webhook-endpoints?location_id=1&is_active=1&per_page=20" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists the webhook endpoints this account has registered, newest first,\nwith the events each one is subscribed to and whether it is active.\n\nCall it before registering another one: duplicated endpoints are the usual\nreason somebody receives the same event twice and blames the retry policy.\nSecrets are never included \u2014 they are shown once, at creation." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":null,\"location_id\":null,\"url\":\"https:\\\/\\\/example.test\\\/webhooks\\\/9MTvekde\",\"events\":[\"contact.created\",\"message.received\"],\"is_active\":true,\"last_delivery_at\":null,\"created_at\":null,\"updated_at\":null},{\"id\":null,\"location_id\":null,\"url\":\"https:\\\/\\\/example.test\\\/webhooks\\\/KcUoSJav\",\"events\":[\"contact.created\",\"message.received\"],\"is_active\":true,\"last_delivery_at\":null,\"created_at\":null,\"updated_at\":null}],\"links\":{\"first\":\"\\\/?page=1\",\"last\":\"\\\/?page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"links\":[{\"url\":null,\"label\":\"« Previous\",\"page\":null,\"active\":false},{\"url\":\"\\\/?page=1\",\"label\":\"1\",\"page\":1,\"active\":true},{\"url\":null,\"label\":\"Next »\",\"page\":null,\"active\":false}],\"path\":\"\\\/\",\"per_page\":20,\"to\":2,\"total\":2}}", "name": "" } ] }, { "name": "Register a webhook endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/webhook-endpoints", "query": [], "raw": "{{baseUrl}}\/api\/webhook-endpoints" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"location_id\":1,\"url\":\"https:\\\/\\\/hooks.example.com\\\/herd\",\"events\":[\"contact.created\",\"contact.updated\"],\"is_active\":true}" }, "description": "Returns the new endpoint including a freshly generated `secret`. **Save\nthis secret immediately**: it is only returned on this create call and on\nsubsequent `show`\/`index` calls if the endpoint is still active." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"location_id\":null,\"url\":\"https:\\\/\\\/example.test\\\/webhooks\\\/tP7QtxDt\",\"events\":[\"contact.created\",\"message.received\"],\"is_active\":true,\"last_delivery_at\":null,\"created_at\":null,\"updated_at\":null,\"secret\":\"nHsIVY0AexDAbMktLudb8xsq6Ofw0OXkmU7NjPL1\"}}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\":\"Url no es una direcci\u00f3n web v\u00e1lida.\",\"errors\":{\"url\":[\"Url no es una direcci\u00f3n web v\u00e1lida.\"]}}", "name": "Not a URL" }, { "header": [], "code": 422, "body": "{\"message\":\"Events.0 no es una opci\u00f3n v\u00e1lida.\",\"errors\":{\"events.0\":[\"Events.0 no es una opci\u00f3n v\u00e1lida.\"]}}", "name": "An event name that does not exist" } ] }, { "name": "Fetch a webhook endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/webhook-endpoints\/:webhookEndpoint_id", "query": [], "raw": "{{baseUrl}}\/api\/webhook-endpoints\/:webhookEndpoint_id", "variable": [ { "id": "webhookEndpoint_id", "key": "webhookEndpoint_id", "value": "6", "description": "Endpoint ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns one webhook endpoint by id: its URL, the events it is subscribed\nto and whether it is active. **The\nsigning secret is not returned here** \u2014 it is shown once, when the\nendpoint is created. If you lost it, delete the endpoint and register it\nagain; there is no way to read it back, which is the point.\n\nTo see what has actually been delivered, use\n`GET \/api\/webhook-endpoints\/{id}\/deliveries`." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"location_id\":null,\"url\":\"https:\\\/\\\/example.test\\\/webhooks\\\/Mh00hWJg\",\"events\":[\"contact.created\",\"message.received\"],\"is_active\":true,\"last_delivery_at\":null,\"created_at\":null,\"updated_at\":null}}", "name": "" }, { "header": [], "code": 404, "body": "{\"message\":\"No query results for model.\"}", "name": "Does not exist, or belongs to another location" } ] }, { "name": "Update a webhook endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/webhook-endpoints\/:webhookEndpoint_id", "query": [], "raw": "{{baseUrl}}\/api\/webhook-endpoints\/:webhookEndpoint_id", "variable": [ { "id": "webhookEndpoint_id", "key": "webhookEndpoint_id", "value": "6", "description": "Endpoint ID." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"url\":\"https:\\\/\\\/hooks.example.com\\\/herd\",\"events\":[\"architecto\"],\"is_active\":false}" }, "description": "Updates a webhook endpoint by id, changing only the fields you send. To\nrotate the signing secret, delete and recreate." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":null,\"location_id\":null,\"url\":\"https:\\\/\\\/example.test\\\/webhooks\\\/USS1QLNW\",\"events\":[\"contact.created\",\"message.received\"],\"is_active\":true,\"last_delivery_at\":null,\"created_at\":null,\"updated_at\":null}}", "name": "" } ] }, { "name": "Delete a webhook endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/webhook-endpoints\/:webhookEndpoint_id", "query": [], "raw": "{{baseUrl}}\/api\/webhook-endpoints\/:webhookEndpoint_id", "variable": [ { "id": "webhookEndpoint_id", "key": "webhookEndpoint_id", "value": "6", "description": "Endpoint ID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Removes the endpoint and invalidates its signing secret. Historical\n`WebhookDelivery` records remain for audit." }, "response": [ { "header": [], "code": 200, "body": "{ \"message\": \"Webhook endpoint deleted.\" }", "name": "" } ] }, { "name": "List delivery attempts for an endpoint", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/webhook-endpoints\/:webhookEndpoint_id\/deliveries", "query": [ { "key": "per_page", "value": "20", "description": "Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/webhook-endpoints\/:webhookEndpoint_id\/deliveries?per_page=20", "variable": [ { "id": "webhookEndpoint_id", "key": "webhookEndpoint_id", "value": "6", "description": "Endpoint ID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns recent delivery attempts (one row per HTTP call, including retries),\nnewest first. Useful for debugging non-2xx responses from your endpoint." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":null,\"endpoint_id\":229,\"event_type\":\"contact.created\",\"response_status\":null,\"attempts\":0,\"delivered_at\":null,\"created_at\":null},{\"id\":null,\"endpoint_id\":230,\"event_type\":\"contact.created\",\"response_status\":null,\"attempts\":0,\"delivered_at\":null,\"created_at\":null}],\"links\":{\"first\":\"\\\/?page=1\",\"last\":\"\\\/?page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"links\":[{\"url\":null,\"label\":\"« Previous\",\"page\":null,\"active\":false},{\"url\":\"\\\/?page=1\",\"label\":\"1\",\"page\":1,\"active\":true},{\"url\":null,\"label\":\"Next »\",\"page\":null,\"active\":false}],\"path\":\"\\\/\",\"per_page\":20,\"to\":2,\"total\":2}}", "name": "" } ] } ] }, { "name": "Notifications", "description": "\nPer-user in-app notifications driven by Laravel's database notification\nchannel. Notifications carry a `type` (Laravel class FQN) and a `data` payload\nspecific to the notification.", "item": [ { "name": "List notifications", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/notifications", "query": [ { "key": "unread", "value": "1", "description": "Only return unread notifications.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Rows per page. Default 25, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/notifications?unread=1&per_page=25" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Lists the notifications of the user the token belongs to, newest first.\nPass `unread=true` to restrict to unread items." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [\n {\n \"id\": \"9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234\",\n \"type\": \"App\\\\Notifications\\\\NewMessageReceived\",\n \"data\": { \"conversation_id\": 17, \"preview\": \"Hi Ada!\" },\n \"read_at\": null,\n \"created_at\": \"2026-06-05T13:42:00+00:00\"\n }\n ],\n \"meta\": {\n \"current_page\": 1,\n \"last_page\": 4,\n \"per_page\": 25,\n \"total\": 87,\n \"unread_count\": 12\n }\n}", "name": "" } ] }, { "name": "Unread count", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/notifications\/unread-count", "query": [], "raw": "{{baseUrl}}\/api\/notifications\/unread-count" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns how many notifications you have unread, as a single integer \u2014 a\nlightweight endpoint for badge polling." }, "response": [ { "header": [], "code": 200, "body": "{ \"unread_count\": 12 }", "name": "" } ] }, { "name": "Mark a notification as read", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/notifications\/:id\/read", "query": [], "raw": "{{baseUrl}}\/api\/notifications\/:id\/read", "variable": [ { "id": "id", "key": "id", "value": "9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234", "description": "Notification UUID." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Marks one notification as read. Idempotent: marking an already-read\nnotification is a no-op (returns the\nexisting read_at)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"id\": \"9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234\",\n \"type\": \"App\\\\Notifications\\\\NewMessageReceived\",\n \"data\": { \"conversation_id\": 17, \"preview\": \"Hi Ada!\" },\n \"read_at\": \"2026-06-05T13:43:00+00:00\",\n \"created_at\": \"2026-06-05T13:42:00+00:00\"\n },\n \"unread_count\": 11\n}", "name": "" }, { "header": [], "code": 404, "body": "{\"message\":\"Not Found\"}", "name": "Not yours, or the UUID does not exist" } ] }, { "name": "Mark all notifications as read", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/notifications\/read-all", "query": [], "raw": "{{baseUrl}}\/api\/notifications\/read-all" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Marks every notification of the user the token belongs to as read, in one\ncall. It affects **your** notifications only \u2014 the\nones belonging to the user the token was issued for \u2014 so it can never\nclear somebody else's inbox.\n\nMarking everything read is not the same as deleting: the notifications\nstay readable, they just stop counting." }, "response": [ { "header": [], "code": 200, "body": "{ \"unread_count\": 0 }", "name": "" } ] }, { "name": "Update notification preferences", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/notifications\/preferences", "query": [], "raw": "{{baseUrl}}\/api\/notifications\/preferences" }, "method": "PUT", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"muted\":[\"App\\\\Notifications\\\\NewMessageReceived\"]}" }, "description": "Updates your notification preferences. Currently only the `muted` list is\nsupported \u2014 notifications whose `type`\nmatches an entry in the list are skipped at delivery time. Provide the\nfull desired list (full-replace, not append)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"muted\": [\"App\\\\Notifications\\\\NewMessageReceived\"]\n }\n}", "name": "" }, { "header": [], "code": 422, "body": "{\"message\":\"Muted debe ser una lista.\",\"errors\":{\"muted\":[\"Muted debe ser una lista.\"]}}", "name": "Not a list" } ] } ] }, { "name": "Audit Log", "description": "\nRead-only timeline of mutations across the workspace. Every create\/update\/\ndelete on auditable models (contacts, tags, smart-lists, etc.) appends one\nrow containing the actor (`user_id`), action verb, subject reference, and a\ndiff of old\/new values.", "item": [ { "name": "List audit log entries", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/audit-logs", "query": [ { "key": "subject_type", "value": "App%5CModels%5CContact", "description": "Eloquent class FQN of the audited model.", "disabled": false }, { "key": "subject_id", "value": "42", "description": "Audited record ID.", "disabled": false }, { "key": "user_id", "value": "7", "description": "Filter by actor.", "disabled": false }, { "key": "action", "value": "updated", "description": "One of `created`, `updated`, `deleted`, `bulk_deleted`, `owner_changed`.", "disabled": false }, { "key": "from", "value": "2026-06-01", "description": "date Lower bound on `created_at` (inclusive, ISO-8601).", "disabled": false }, { "key": "to", "value": "2026-06-05", "description": "date Upper bound on `created_at` (inclusive, ISO-8601).", "disabled": false }, { "key": "per_page", "value": "50", "description": "Rows per page. Default 50, maximum 200. See [Lists, paging and filters](#lists-paging-and-filters).", "disabled": false } ], "raw": "{{baseUrl}}\/api\/audit-logs?subject_type=App%5CModels%5CContact&subject_id=42&user_id=7&action=updated&from=2026-06-01&to=2026-06-05&per_page=50" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"subject_type\":\"b\",\"subject_id\":16,\"user_id\":16,\"action\":\"n\",\"from\":\"2026-08-26T02:19:50\",\"to\":\"2026-08-26T02:19:50\",\"per_page\":7}" }, "description": "Lists the audit log entries of the token's location, newest first. All\nfilters are optional and additive.\n\n**Scoped to the location the token belongs to.** Entries from another\nlocation are never returned, and there is no parameter that widens it.\n\nEverybody in the location can read it, on purpose \u2014 including `viewer`.\nThe log exists to settle an argument between two people, and a record only\none of them can open settles nothing." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":null,\"user_id\":3783,\"location_id\":null,\"action\":\"deleted\",\"subject_type\":\"App\\\\Models\\\\Contact\",\"subject_id\":23891,\"old_values\":null,\"new_values\":{\"first_name\":\"Rowan\"},\"ip_address\":\"197.119.215.250\",\"user_agent\":\"Mozilla\\\/5.0 (X11; Linux x86_64) AppleWebKit\\\/5340 (KHTML, like Gecko) Chrome\\\/40.0.882.0 Mobile Safari\\\/5340\",\"created_at\":null},{\"id\":null,\"user_id\":3785,\"location_id\":null,\"action\":\"created\",\"subject_type\":\"App\\\\Models\\\\Contact\",\"subject_id\":23892,\"old_values\":null,\"new_values\":{\"first_name\":\"Nelson\"},\"ip_address\":\"109.9.175.184\",\"user_agent\":\"Mozilla\\\/5.0 (Macintosh; U; Intel Mac OS X 10_7_5 rv:4.0; en-US) AppleWebKit\\\/535.23.7 (KHTML, like Gecko) Version\\\/5.0 Safari\\\/535.23.7\",\"created_at\":null}],\"links\":{\"first\":\"\\\/?page=1\",\"last\":\"\\\/?page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"links\":[{\"url\":null,\"label\":\"« Previous\",\"page\":null,\"active\":false},{\"url\":\"\\\/?page=1\",\"label\":\"1\",\"page\":1,\"active\":true},{\"url\":null,\"label\":\"Next »\",\"page\":null,\"active\":false}],\"path\":\"\\\/\",\"per_page\":50,\"to\":2,\"total\":2}}", "name": "" }, { "header": [], "code": 403, "body": "{\"message\":\"This action is unauthorized.\"}", "name": "A token with no location resolved" }, { "header": [], "code": 422, "body": "{\"message\":\"Per page no puede ser mayor que 200.\",\"errors\":{\"per_page\":[\"Per page no puede ser mayor que 200.\"]}}", "name": "A page size above the ceiling" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }