openapi: 3.1.0
info:
  title: 'Klozzo API'
  description: 'External integrator API for Klozzo. JSON over HTTPS, Bearer token auth.'
  version: 1.0.0
  contact:
    name: 'Soporte de Klozzo'
    url: 'https://klozzo.com/ayuda'
  termsOfService: 'https://klozzo.com/terminos'
servers:
  -
    url: 'https://klozzo.com'
tags:
  -
    name: 'Lead capture'
    description: "\nThe door a person comes in through when they raise their hand (U1-1)."
  -
    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."
  -
    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."
  -
    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."
  -
    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."
  -
    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."
  -
    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."
  -
    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."
  -
    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)."
  -
    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 — set it once and every later\ncall can find the company by your identifier instead of ours."
  -
    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 — 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)."
  -
    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."
  -
    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."
  -
    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."
  -
    name: 'Pixel · 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 — 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 — 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."
  -
    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 — it is returned only on the\ninitial create response and on `show`; rotate by deleting and recreating."
  -
    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."
  -
    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."
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: 'Issue a personal-access token from **Settings → API tokens** and send it as `Authorization: Bearer <token>` on every request. Which location a token acts on, what an ability means and what to do about a `403` are explained in [Authenticating requests](/docs/guides/authenticating-requests).'
security:
  -
    default: []
paths:
  /api/leads:
    post:
      summary: 'Capture a lead'
      operationId: captureALead
      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` —\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 — 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 — see\n[Idempotency](#idempotency)."
      parameters: []
      responses:
        200:
          description: 'Returning person, enriched'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      contact:
                        type: object
                        properties:
                          id:
                            type: string
                            examples:
                              - 01KZ2P...
                          first_name:
                            type: string
                            examples:
                              - Jonathan
                      contact_created:
                        type: boolean
                        examples:
                          - false
                      touch_id:
                        type: string
                        examples:
                          - 01KZ2Q...
                      applied:
                        type: object
                        properties:
                          last_name:
                            type: string
                            examples:
                              - Zapata
                      skipped:
                        type: object
                        properties:
                          source:
                            type: string
                            examples:
                              - immutable
                      unmapped_keys:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - presupuesto_mensual
                examples:
                  -
                    data:
                      contact:
                        id: 01KZ2P...
                        first_name: Jonathan
                      contact_created: false
                      touch_id: 01KZ2Q...
                      applied:
                        last_name: Zapata
                      skipped:
                        source: immutable
                      unmapped_keys:
                        - presupuesto_mensual
        422:
          description: 'No way to reach them'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Hace falta al menos un correo electrónico o un teléfono para poder identificar a la persona.'
                  errors:
                    type: object
                    properties:
                      email:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - 'Hace falta al menos un correo electrónico o un teléfono para poder identificar a la persona.'
                examples:
                  -
                    message: 'Hace falta al menos un correo electrónico o un teléfono para poder identificar a la persona.'
                    errors:
                      email:
                        - 'Hace falta al menos un correo electrónico o un teléfono para poder identificar a la persona.'
      tags:
        - 'Lead capture'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type:
                    - string
                    - 'null'
                  description: "The person's email. Required unless `phone` is given."
                  examples:
                    - ana.lopez@example.com
                phone:
                  type:
                    - string
                    - 'null'
                  description: "The person's phone. Required unless `email` is given. E.164 with the country code — `+525555555555`. A local number is only accepted together with `phone_country`; without either the request is rejected."
                  examples:
                    - '+525555555555'
                phone_country:
                  type:
                    - string
                    - 'null'
                  description: 'ISO-3166-1 alpha-2, e.g. `MX`. Only needed when `phone` has no `+` country code; ignored when it does.'
                  examples:
                    - MX
                first_name:
                  type:
                    - string
                    - 'null'
                  description: ''
                  examples:
                    - Jonathan
                last_name:
                  type:
                    - string
                    - 'null'
                  description: ''
                  examples:
                    - Zapata
                company_name:
                  type:
                    - string
                    - 'null'
                  description: ''
                  examples:
                    - Klozzo
                timezone:
                  type:
                    - string
                    - 'null'
                  description: 'IANA timezone.'
                  examples:
                    - America/Mexico_City
                source:
                  type:
                    - string
                    - 'null'
                  description: 'How they reached you, recorded once and never overwritten.'
                  examples:
                    - landing-verano
                interest:
                  type:
                    - string
                    - 'null'
                  description: 'What they asked for, in their own words. Stored as text; matched to a product only if one by that name already exists.'
                  examples:
                    - 'Paquete de firmas'
                landing_page:
                  type:
                    - string
                    - 'null'
                  description: 'The page they arrived on.'
                  examples:
                    - 'https://klozzo.com/producto-b'
                referrer:
                  type:
                    - string
                    - 'null'
                  description: 'The referring URL.'
                  examples:
                    - 'https://example.com/blog/precios'
                utm:
                  type:
                    - object
                    - 'null'
                  description: 'Campaign parameters. Also accepted flat at the top level.'
                  properties:
                    utm_source:
                      type:
                        - string
                        - 'null'
                      description: ''
                      examples:
                        - adwords
                    utm_medium:
                      type:
                        - string
                        - 'null'
                      description: ''
                      examples:
                        - ppc
                    utm_campaign:
                      type:
                        - string
                        - 'null'
                      description: ''
                      examples:
                        - verano
                    utm_term:
                      type:
                        - string
                        - 'null'
                      description: 'Must not be greater than 150 characters.'
                      examples:
                        - 'y'
                    utm_content:
                      type:
                        - string
                        - 'null'
                      description: 'Must not be greater than 150 characters.'
                      examples:
                        - k
                    gclid:
                      type:
                        - string
                        - 'null'
                      description: ''
                      examples:
                        - Cj0KCQjw
                    fbclid:
                      type:
                        - string
                        - 'null'
                      description: 'Must not be greater than 255 characters.'
                      examples:
                        - m
                    msclkid:
                      type:
                        - string
                        - 'null'
                      description: 'Must not be greater than 255 characters.'
                      examples:
                        - 'y'
                  examples:
                    - []
                custom_field_values:
                  type:
                    - object
                    - 'null'
                  description: 'Values keyed by custom field `key`. Unknown keys are kept, not created.'
                  properties: {  }
                  examples:
                    - []
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/leads\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"email\\\": \\\"ana.lopez@example.com\\\",\n    \\\"phone\\\": \\\"+525555555555\\\",\n    \\\"phone_country\\\": \\\"MX\\\",\n    \\\"first_name\\\": \\\"Jonathan\\\",\n    \\\"last_name\\\": \\\"Zapata\\\",\n    \\\"company_name\\\": \\\"Klozzo\\\",\n    \\\"timezone\\\": \\\"America\\\\/Mexico_City\\\",\n    \\\"source\\\": \\\"landing-verano\\\",\n    \\\"interest\\\": \\\"Paquete de firmas\\\",\n    \\\"landing_page\\\": \\\"https:\\\\/\\\\/klozzo.com\\\\/producto-b\\\",\n    \\\"referrer\\\": \\\"https:\\\\/\\\\/example.com\\\\/blog\\\\/precios\\\",\n    \\\"utm\\\": {\n        \\\"utm_source\\\": \\\"adwords\\\",\n        \\\"utm_medium\\\": \\\"ppc\\\",\n        \\\"utm_campaign\\\": \\\"verano\\\",\n        \\\"utm_term\\\": \\\"y\\\",\n        \\\"utm_content\\\": \\\"k\\\",\n        \\\"gclid\\\": \\\"Cj0KCQjw\\\",\n        \\\"fbclid\\\": \\\"m\\\",\n        \\\"msclkid\\\": \\\"y\\\"\n    },\n    \\\"custom_field_values\\\": []\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/leads\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"email\": \"ana.lopez@example.com\",\n    \"phone\": \"+525555555555\",\n    \"phone_country\": \"MX\",\n    \"first_name\": \"Jonathan\",\n    \"last_name\": \"Zapata\",\n    \"company_name\": \"Klozzo\",\n    \"timezone\": \"America\\/Mexico_City\",\n    \"source\": \"landing-verano\",\n    \"interest\": \"Paquete de firmas\",\n    \"landing_page\": \"https:\\/\\/klozzo.com\\/producto-b\",\n    \"referrer\": \"https:\\/\\/example.com\\/blog\\/precios\",\n    \"utm\": {\n        \"utm_source\": \"adwords\",\n        \"utm_medium\": \"ppc\",\n        \"utm_campaign\": \"verano\",\n        \"utm_term\": \"y\",\n        \"utm_content\": \"k\",\n        \"gclid\": \"Cj0KCQjw\",\n        \"fbclid\": \"m\",\n        \"msclkid\": \"y\"\n    },\n    \"custom_field_values\": []\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/leads';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'email' => 'ana.lopez@example.com',\n            'phone' => '+525555555555',\n            'phone_country' => 'MX',\n            'first_name' => 'Jonathan',\n            'last_name' => 'Zapata',\n            'company_name' => 'Klozzo',\n            'timezone' => 'America/Mexico_City',\n            'source' => 'landing-verano',\n            'interest' => 'Paquete de firmas',\n            'landing_page' => 'https://klozzo.com/producto-b',\n            'referrer' => 'https://example.com/blog/precios',\n            'utm' => ['utm_source' => 'adwords', 'utm_medium' => 'ppc', 'utm_campaign' => 'verano', 'utm_term' => 'y', 'utm_content' => 'k', 'gclid' => 'Cj0KCQjw', 'fbclid' => 'm', 'msclkid' => 'y'],\n            'custom_field_values' => [],\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/leads'\npayload = {\n    \"email\": \"ana.lopez@example.com\",\n    \"phone\": \"+525555555555\",\n    \"phone_country\": \"MX\",\n    \"first_name\": \"Jonathan\",\n    \"last_name\": \"Zapata\",\n    \"company_name\": \"Klozzo\",\n    \"timezone\": \"America\\/Mexico_City\",\n    \"source\": \"landing-verano\",\n    \"interest\": \"Paquete de firmas\",\n    \"landing_page\": \"https:\\/\\/klozzo.com\\/producto-b\",\n    \"referrer\": \"https:\\/\\/example.com\\/blog\\/precios\",\n    \"utm\": {\n        \"utm_source\": \"adwords\",\n        \"utm_medium\": \"ppc\",\n        \"utm_campaign\": \"verano\",\n        \"utm_term\": \"y\",\n        \"utm_content\": \"k\",\n        \"gclid\": \"Cj0KCQjw\",\n        \"fbclid\": \"m\",\n        \"msclkid\": \"y\"\n    },\n    \"custom_field_values\": []\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  /api/contacts/properties:
    get:
      summary: 'List contact properties'
      operationId: listContactProperties
      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 —\n`location` is `root` for top-level fields and `custom_field_values` for\nthe rest — and which ones cannot be written here, with the alternative\nroute when there is one."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                          examples:
                            - first_name
                        label:
                          type: string
                          examples:
                            - Nombre
                        type:
                          type: string
                          examples:
                            - text
                        group:
                          type: string
                          examples:
                            - native
                        location:
                          type: string
                          examples:
                            - root
                        writable:
                          type: boolean
                          examples:
                            - true
                        required:
                          type: boolean
                          examples:
                            - true
                    examples:
                      -
                        -
                          key: first_name
                          label: Nombre
                          type: text
                          group: native
                          location: root
                          writable: true
                          required: true
                examples:
                  -
                    data:
                      -
                        key: first_name
                        label: Nombre
                        type: text
                        group: native
                        location: root
                        writable: true
                        required: true
      tags:
        - Contacts
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/contacts/properties\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/properties\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/properties';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/properties'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
  /api/lead-stages:
    get:
      summary: 'List lead stages'
      operationId: listLeadStages
      description: "Lists the lead stages this account defines — 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 — not a fixed list shipped with the\nproduct — 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 — 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`."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'A location with the default stages'
                    type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              examples:
                                - 1
                            name:
                              type: string
                              examples:
                                - Nuevo
                            slug:
                              type: string
                              examples:
                                - nuevo
                            color:
                              type: string
                              examples:
                                - '#22c55e'
                            position:
                              type: integer
                              examples:
                                - 0
                            contacts_count:
                              type: integer
                              examples:
                                - 42
                        examples:
                          -
                            -
                              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:
                        type: object
                        properties:
                          usage:
                            type: string
                            examples:
                              - 'Manda el `id` en `lead_stage_id` al crear o actualizar un contacto: {"lead_stage_id": 1}. `null` lo deja sin estado.'
                    examples:
                      -
                        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.'
                  -
                    description: 'No location resolved for this token'
                    type: object
                    properties:
                      data:
                        type: array
                        examples:
                          - []
                      meta:
                        type: object
                        properties:
                          usage:
                            type: string
                            examples:
                              - 'Manda el `id` en `lead_stage_id` al crear o actualizar un contacto: {"lead_stage_id": 1}. `null` lo deja sin estado.'
                    examples:
                      -
                        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.'
        403:
          description: 'The token cannot read contacts'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'This action is unauthorized.'
                examples:
                  -
                    message: 'This action is unauthorized.'
      tags:
        - Contacts
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/lead-stages\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/lead-stages\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/lead-stages';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/lead-stages'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
  /api/contacts:
    get:
      summary: 'List contacts'
      operationId: listContacts
      description: "Returns a paginated list of contacts owned by the authenticated user.\nSupports full-text search across name, email, phone, and company."
      parameters:
        -
          in: query
          name: search
          description: 'Fragment matched against first/last name, email, phone, company.'
          required: false
          schema:
            type: string
            description: 'Fragment matched against first/last name, email, phone, company.'
            examples:
              - ada
        -
          in: query
          name: contact_type
          description: 'Filter by type. One of `lead`, `customer`, `partner`.'
          required: false
          schema:
            type: string
            description: 'Filter by type. One of `lead`, `customer`, `partner`.'
            examples:
              - lead
        -
          in: query
          name: sort
          description: 'Column to sort by (e.g. `created_at`, `last_name`). Defaults to newest first.'
          required: false
          schema:
            type: string
            description: 'Column to sort by (e.g. `created_at`, `last_name`). Defaults to newest first.'
            examples:
              - created_at
        -
          in: query
          name: direction
          description: 'Sort direction, `asc` or `desc`.'
          required: false
          schema:
            type: string
            description: 'Sort direction, `asc` or `desc`.'
            examples:
              - desc
        -
          in: query
          name: per_page
          description: 'Rows per page. Default 25, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
          required: false
          schema:
            type: integer
            description: 'Rows per page. Default 25, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
            examples:
              - 25
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        ulid:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        first_name:
                          type: string
                          examples:
                            - Morgan
                        last_name:
                          type: string
                          examples:
                            - Hirthe
                        full_name:
                          type: string
                          examples:
                            - 'Morgan Hirthe'
                        email:
                          type: string
                          examples:
                            - dare.emelie@example.com
                        email_verified_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        email_verification_excluded:
                          type: boolean
                          examples:
                            - false
                        email_verification_sent_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        phone:
                          type: string
                          examples:
                            - '+12025550100'
                        phone_e164:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        phone_country:
                          type: string
                          examples:
                            - US
                        phone_type:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        has_whatsapp:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        whatsapp_checked_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        whatsapp_history_synced_until:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        whatsapp_history_exhausted:
                          type: boolean
                          examples:
                            - false
                        avatar_url:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        additional_emails:
                          type: array
                          examples:
                            - []
                        additional_phones:
                          type: array
                          examples:
                            - []
                        company_name:
                          type: string
                          examples:
                            - 'McLaughlin, Leuschke and Bauch'
                        contact_type:
                          type: string
                          examples:
                            - lead
                        timezone:
                          type: string
                          examples:
                            - Asia/Famagusta
                        source:
                          type: string
                          examples:
                            - import
                        source_number:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        date_of_birth:
                          type: string
                          examples:
                            - '2003-07-15'
                        dnd_all:
                          type: boolean
                          examples:
                            - false
                        dnd_email:
                          type: boolean
                          examples:
                            - false
                        dnd_sms:
                          type: boolean
                          examples:
                            - false
                        dnd_calls:
                          type: boolean
                          examples:
                            - false
                        dnd_voicemail:
                          type: boolean
                          examples:
                            - false
                        dnd_gmb:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        dnd_fb_messenger:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        dnd_meta:
                          type: object
                          properties: {  }
                        last_activity_at:
                          type: string
                          examples:
                            - '2026-08-17T14:16:42+00:00'
                        created_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        updated_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        owner_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        lead_stage_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                    examples:
                      -
                        -
                          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:
                    type: object
                    properties:
                      first:
                        type: string
                        examples:
                          - '/?page=1'
                      last:
                        type: string
                        examples:
                          - '/?page=1'
                      prev:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      next:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        examples:
                          - 1
                      from:
                        type: integer
                        examples:
                          - 1
                      last_page:
                        type: integer
                        examples:
                          - 1
                      links:
                        type: array
                        items:
                          type: object
                          properties:
                            url:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            label:
                              type: string
                              examples:
                                - '&laquo; Previous'
                            page:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            active:
                              type: boolean
                              examples:
                                - false
                        examples:
                          -
                            -
                              url: null
                              label: '&laquo; Previous'
                              page: null
                              active: false
                            -
                              url: '/?page=1'
                              label: '1'
                              page: 1
                              active: true
                            -
                              url: null
                              label: 'Next &raquo;'
                              page: null
                              active: false
                      path:
                        type: string
                        examples:
                          - /
                      per_page:
                        type: integer
                        examples:
                          - 25
                      to:
                        type: integer
                        examples:
                          - 2
                      total:
                        type: integer
                        examples:
                          - 2
                examples:
                  -
                    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: '&laquo; Previous'
                          page: null
                          active: false
                        -
                          url: '/?page=1'
                          label: '1'
                          page: 1
                          active: true
                        -
                          url: null
                          label: 'Next &raquo;'
                          page: null
                          active: false
                      path: /
                      per_page: 25
                      to: 2
                      total: 2
      tags:
        - Contacts
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/contacts?search=ada&contact_type=lead&sort=created_at&direction=desc&per_page=25\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts\"\n);\n\nconst params = {\n    \"search\": \"ada\",\n    \"contact_type\": \"lead\",\n    \"sort\": \"created_at\",\n    \"direction\": \"desc\",\n    \"per_page\": \"25\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'search' => 'ada',\n            'contact_type' => 'lead',\n            'sort' => 'created_at',\n            'direction' => 'desc',\n            'per_page' => '25',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts'\nparams = {\n  'search': 'ada',\n  'contact_type': 'lead',\n  'sort': 'created_at',\n  'direction': 'desc',\n  'per_page': '25',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers, params=params)\nresponse.json()"
    post:
      summary: 'Create a contact'
      operationId: createAContact
      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 — 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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      ulid:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      first_name:
                        type: string
                        examples:
                          - Christelle
                      last_name:
                        type: string
                        examples:
                          - Bailey
                      full_name:
                        type: string
                        examples:
                          - 'Christelle Bailey'
                      email:
                        type: string
                        examples:
                          - rowan.gulgowski@example.com
                      email_verified_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      email_verification_excluded:
                        type: boolean
                        examples:
                          - false
                      email_verification_sent_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      phone:
                        type: string
                        examples:
                          - '+12025550102'
                      phone_e164:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      phone_country:
                        type: string
                        examples:
                          - CO
                      phone_type:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      has_whatsapp:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      whatsapp_checked_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      whatsapp_history_synced_until:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      whatsapp_history_exhausted:
                        type: boolean
                        examples:
                          - false
                      avatar_url:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      additional_emails:
                        type: array
                        examples:
                          - []
                      additional_phones:
                        type: array
                        examples:
                          - []
                      company_name:
                        type: string
                        examples:
                          - Dach-Gaylord
                      contact_type:
                        type: string
                        examples:
                          - customer
                      timezone:
                        type: string
                        examples:
                          - Africa/Dakar
                      source:
                        type: string
                        examples:
                          - import
                      source_number:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      date_of_birth:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      dnd_all:
                        type: boolean
                        examples:
                          - false
                      dnd_email:
                        type: boolean
                        examples:
                          - false
                      dnd_sms:
                        type: boolean
                        examples:
                          - false
                      dnd_calls:
                        type: boolean
                        examples:
                          - false
                      dnd_voicemail:
                        type: boolean
                        examples:
                          - false
                      dnd_gmb:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      dnd_fb_messenger:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      dnd_meta:
                        type: object
                        properties: {  }
                      last_activity_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      owner_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      lead_stage_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        403:
          description: 'not authorized'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'This action is unauthorized.'
                examples:
                  -
                    message: 'This action is unauthorized.'
        422:
          description: 'duplicate email blocked'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Ya existe un contacto con este correo electrónico.'
                  errors:
                    type: object
                    properties:
                      email:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - 'Ya existe un contacto con este correo electrónico.'
                examples:
                  -
                    message: 'Ya existe un contacto con este correo electrónico.'
                    errors:
                      email:
                        - 'Ya existe un contacto con este correo electrónico.'
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  description: 'Contact first name.'
                  examples:
                    - Ada
                last_name:
                  type:
                    - string
                    - 'null'
                  description: 'Contact last name.'
                  examples:
                    - Lovelace
                email:
                  type:
                    - string
                    - 'null'
                  description: 'Primary email; unique within scope if duplicate-block is on.'
                  examples:
                    - ada@example.com
                phone:
                  type:
                    - string
                    - 'null'
                  description: 'E.164 with the country code — `+525555555555`. A local number is only accepted together with `phone_country`; without either the request is rejected. Stored normalised to E.164.'
                  examples:
                    - '+525555555555'
                phone_country:
                  type:
                    - string
                    - 'null'
                  description: 'ISO-3166-1 alpha-2, e.g. `MX`. Only needed when `phone` has no `+` country code; ignored when it does.'
                  examples:
                    - MX
                phone_type:
                  type:
                    - string
                    - 'null'
                  description: 'One of `mobile`, `home`, `work`, `other`.'
                  examples:
                    - mobile
                company_name:
                  type:
                    - string
                    - 'null'
                  description: ''
                  examples:
                    - 'Analytical Engines Ltd.'
                company_id:
                  type:
                    - integer
                    - 'null'
                  description: 'The <code>id</code> of an existing record in the companies table.'
                  examples:
                    - 16
                contact_type:
                  type:
                    - string
                    - 'null'
                  description: 'One of `lead`, `customer`, `partner`.'
                  examples:
                    - lead
                lead_stage_id:
                  type:
                    - integer
                    - 'null'
                  description: 'The <code>id</code> of an existing record in the lead_stages table.'
                  examples:
                    - 16
                timezone:
                  type:
                    - string
                    - 'null'
                  description: 'IANA timezone.'
                  examples:
                    - America/Mexico_City
                source:
                  type:
                    - string
                    - 'null'
                  description: 'Free-form acquisition source.'
                  examples:
                    - web
                channel_integration_id:
                  type:
                    - integer
                    - 'null'
                  description: 'The <code>id</code> of an existing record in the channel_integrations table.'
                  examples:
                    - 16
                date_of_birth:
                  type:
                    - string
                    - 'null'
                  description: 'ISO-8601 date.'
                  examples:
                    - '1815-12-10'
                avatar:
                  type:
                    - string
                    - 'null'
                  format: binary
                  description: 'Image, max 2MB. Only via multipart/form-data.'
                additional_emails:
                  type: array
                  description: 'Up to 5 extra email addresses.'
                  items:
                    type: string
                  examples:
                    -
                      - architecto
                additional_phones:
                  type: array
                  description: 'Up to 5 extra numbers, same rules as `phone`. They share the single `phone_country`, so send them in E.164 if they are from different countries.'
                  items:
                    type: string
                  examples:
                    -
                      - architecto
                dnd_all:
                  type:
                    - boolean
                    - 'null'
                  description: 'Master Do-Not-Disturb toggle.'
                  examples:
                    - false
                dnd_email:
                  type:
                    - boolean
                    - 'null'
                  description: 'Block email for this person. Independent of `dnd_all`, which blocks everything.'
                  examples:
                    - false
                dnd_sms:
                  type:
                    - boolean
                    - 'null'
                  description: 'Block SMS for this person.'
                  examples:
                    - false
                dnd_calls:
                  type:
                    - boolean
                    - 'null'
                  description: 'Block outbound calls for this person.'
                  examples:
                    - false
                dnd_voicemail:
                  type:
                    - boolean
                    - 'null'
                  description: 'Block leaving voicemail for this person.'
                  examples:
                    - false
                dnd_gmb:
                  type:
                    - boolean
                    - 'null'
                  description: 'Block Google Business Messages for this person.'
                  examples:
                    - false
                dnd_fb_messenger:
                  type:
                    - boolean
                    - 'null'
                  description: 'Block Facebook Messenger for this person.'
                  examples:
                    - false
                auto_engage:
                  type:
                    - boolean
                    - 'null'
                  description: 'Enable automated engagement workflows.'
                  examples:
                    - true
                custom_field_values:
                  type:
                    - object
                    - 'null'
                  description: 'Map of `custom_field_id => value`.'
                  properties: {  }
                  examples:
                    - []
              required:
                - first_name
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/contacts\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: multipart/form-data\" \\\n    --header \"Accept: application/json\" \\\n    --form \"first_name=Ada\"\\\n    --form \"last_name=Lovelace\"\\\n    --form \"email=ada@example.com\"\\\n    --form \"phone=+525555555555\"\\\n    --form \"phone_country=MX\"\\\n    --form \"phone_type=mobile\"\\\n    --form \"company_name=Analytical Engines Ltd.\"\\\n    --form \"company_id=16\"\\\n    --form \"contact_type=lead\"\\\n    --form \"lead_stage_id=16\"\\\n    --form \"timezone=America/Mexico_City\"\\\n    --form \"source=web\"\\\n    --form \"channel_integration_id=16\"\\\n    --form \"date_of_birth=1815-12-10\"\\\n    --form \"additional_emails[]=architecto\"\\\n    --form \"additional_phones[]=architecto\"\\\n    --form \"dnd_all=\"\\\n    --form \"dnd_email=\"\\\n    --form \"dnd_sms=\"\\\n    --form \"dnd_calls=\"\\\n    --form \"dnd_voicemail=\"\\\n    --form \"dnd_gmb=\"\\\n    --form \"dnd_fb_messenger=\"\\\n    --form \"auto_engage=1\"\\\n    --form \"avatar=@/private/var/folders/yw/tssyhl110hs29p29scc2m0jc0000gn/T/phpn370553gbibdcAe8NFE\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"multipart/form-data\",\n    \"Accept\": \"application/json\",\n};\n\nconst body = new FormData();\nbody.append('first_name', 'Ada');\nbody.append('last_name', 'Lovelace');\nbody.append('email', 'ada@example.com');\nbody.append('phone', '+525555555555');\nbody.append('phone_country', 'MX');\nbody.append('phone_type', 'mobile');\nbody.append('company_name', 'Analytical Engines Ltd.');\nbody.append('company_id', '16');\nbody.append('contact_type', 'lead');\nbody.append('lead_stage_id', '16');\nbody.append('timezone', 'America/Mexico_City');\nbody.append('source', 'web');\nbody.append('channel_integration_id', '16');\nbody.append('date_of_birth', '1815-12-10');\nbody.append('additional_emails[]', 'architecto');\nbody.append('additional_phones[]', 'architecto');\nbody.append('dnd_all', '');\nbody.append('dnd_email', '');\nbody.append('dnd_sms', '');\nbody.append('dnd_calls', '');\nbody.append('dnd_voicemail', '');\nbody.append('dnd_gmb', '');\nbody.append('dnd_fb_messenger', '');\nbody.append('auto_engage', '1');\nbody.append('avatar', document.querySelector('input[name=\"avatar\"]').files[0]);\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'multipart/form-data',\n            'Accept' => 'application/json',\n        ],\n        'multipart' => [\n            [\n                'name' => 'first_name',\n                'contents' => 'Ada'\n            ],\n            [\n                'name' => 'last_name',\n                'contents' => 'Lovelace'\n            ],\n            [\n                'name' => 'email',\n                'contents' => 'ada@example.com'\n            ],\n            [\n                'name' => 'phone',\n                'contents' => '+525555555555'\n            ],\n            [\n                'name' => 'phone_country',\n                'contents' => 'MX'\n            ],\n            [\n                'name' => 'phone_type',\n                'contents' => 'mobile'\n            ],\n            [\n                'name' => 'company_name',\n                'contents' => 'Analytical Engines Ltd.'\n            ],\n            [\n                'name' => 'company_id',\n                'contents' => '16'\n            ],\n            [\n                'name' => 'contact_type',\n                'contents' => 'lead'\n            ],\n            [\n                'name' => 'lead_stage_id',\n                'contents' => '16'\n            ],\n            [\n                'name' => 'timezone',\n                'contents' => 'America/Mexico_City'\n            ],\n            [\n                'name' => 'source',\n                'contents' => 'web'\n            ],\n            [\n                'name' => 'channel_integration_id',\n                'contents' => '16'\n            ],\n            [\n                'name' => 'date_of_birth',\n                'contents' => '1815-12-10'\n            ],\n            [\n                'name' => 'additional_emails[]',\n                'contents' => 'architecto'\n            ],\n            [\n                'name' => 'additional_phones[]',\n                'contents' => 'architecto'\n            ],\n            [\n                'name' => 'dnd_all',\n                'contents' => ''\n            ],\n            [\n                'name' => 'dnd_email',\n                'contents' => ''\n            ],\n            [\n                'name' => 'dnd_sms',\n                'contents' => ''\n            ],\n            [\n                'name' => 'dnd_calls',\n                'contents' => ''\n            ],\n            [\n                'name' => 'dnd_voicemail',\n                'contents' => ''\n            ],\n            [\n                'name' => 'dnd_gmb',\n                'contents' => ''\n            ],\n            [\n                'name' => 'dnd_fb_messenger',\n                'contents' => ''\n            ],\n            [\n                'name' => 'auto_engage',\n                'contents' => '1'\n            ],\n            [\n                'name' => 'avatar',\n                'contents' => fopen('/private/var/folders/yw/tssyhl110hs29p29scc2m0jc0000gn/T/phpn370553gbibdcAe8NFE', 'r')\n            ],\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts'\nfiles = {\n  'first_name': (None, 'Ada'),\n  'last_name': (None, 'Lovelace'),\n  'email': (None, 'ada@example.com'),\n  'phone': (None, '+525555555555'),\n  'phone_country': (None, 'MX'),\n  'phone_type': (None, 'mobile'),\n  'company_name': (None, 'Analytical Engines Ltd.'),\n  'company_id': (None, '16'),\n  'contact_type': (None, 'lead'),\n  'lead_stage_id': (None, '16'),\n  'timezone': (None, 'America/Mexico_City'),\n  'source': (None, 'web'),\n  'channel_integration_id': (None, '16'),\n  'date_of_birth': (None, '1815-12-10'),\n  'additional_emails[]': (None, 'architecto'),\n  'additional_phones[]': (None, 'architecto'),\n  'dnd_all': (None, ''),\n  'dnd_email': (None, ''),\n  'dnd_sms': (None, ''),\n  'dnd_calls': (None, ''),\n  'dnd_voicemail': (None, ''),\n  'dnd_gmb': (None, ''),\n  'dnd_fb_messenger': (None, ''),\n  'auto_engage': (None, '1'),\n  'avatar': open('/private/var/folders/yw/tssyhl110hs29p29scc2m0jc0000gn/T/phpn370553gbibdcAe8NFE', 'rb')}\npayload = {\n    \"first_name\": \"Ada\",\n    \"last_name\": \"Lovelace\",\n    \"email\": \"ada@example.com\",\n    \"phone\": \"+525555555555\",\n    \"phone_country\": \"MX\",\n    \"phone_type\": \"mobile\",\n    \"company_name\": \"Analytical Engines Ltd.\",\n    \"company_id\": 16,\n    \"contact_type\": \"lead\",\n    \"lead_stage_id\": 16,\n    \"timezone\": \"America\\/Mexico_City\",\n    \"source\": \"web\",\n    \"channel_integration_id\": 16,\n    \"date_of_birth\": \"1815-12-10\",\n    \"additional_emails\": [\n        \"architecto\"\n    ],\n    \"additional_phones\": [\n        \"architecto\"\n    ],\n    \"dnd_all\": false,\n    \"dnd_email\": false,\n    \"dnd_sms\": false,\n    \"dnd_calls\": false,\n    \"dnd_voicemail\": false,\n    \"dnd_gmb\": false,\n    \"dnd_fb_messenger\": false,\n    \"auto_engage\": true,\n    \"custom_field_values\": []\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'multipart/form-data',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, files=files)\nresponse.json()"
  '/api/contacts/{id}':
    get:
      summary: 'Fetch a contact'
      operationId: fetchAContact
      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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      ulid:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      first_name:
                        type: string
                        examples:
                          - Morgan
                      last_name:
                        type: string
                        examples:
                          - Hirthe
                      full_name:
                        type: string
                        examples:
                          - 'Morgan Hirthe'
                      email:
                        type: string
                        examples:
                          - imclaughlin@example.org
                      email_verified_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      email_verification_excluded:
                        type: boolean
                        examples:
                          - false
                      email_verification_sent_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      phone:
                        type: string
                        examples:
                          - '+12025550103'
                      phone_e164:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      phone_country:
                        type: string
                        examples:
                          - MX
                      phone_type:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      has_whatsapp:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      whatsapp_checked_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      whatsapp_history_synced_until:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      whatsapp_history_exhausted:
                        type: boolean
                        examples:
                          - false
                      avatar_url:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      additional_emails:
                        type: array
                        examples:
                          - []
                      additional_phones:
                        type: array
                        examples:
                          - []
                      company_name:
                        type: string
                        examples:
                          - "O'Keefe Inc"
                      contact_type:
                        type: string
                        examples:
                          - lead
                      timezone:
                        type: string
                        examples:
                          - Pacific/Tongatapu
                      source:
                        type: string
                        examples:
                          - manual
                      source_number:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      date_of_birth:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      dnd_all:
                        type: boolean
                        examples:
                          - false
                      dnd_email:
                        type: boolean
                        examples:
                          - false
                      dnd_sms:
                        type: boolean
                        examples:
                          - false
                      dnd_calls:
                        type: boolean
                        examples:
                          - false
                      dnd_voicemail:
                        type: boolean
                        examples:
                          - false
                      dnd_gmb:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      dnd_fb_messenger:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      dnd_meta:
                        type: object
                        properties: {  }
                      last_activity_at:
                        type: string
                        examples:
                          - '2026-08-09T18:01:18+00:00'
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      owner_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      lead_stage_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        404:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No query results for model [App\Models\Contact].'
                examples:
                  -
                    message: 'No query results for model [App\Models\Contact].'
      tags:
        - Contacts
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/contacts/42\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/42\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/42';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/42'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    put:
      summary: 'Update a contact'
      operationId: updateAContact
      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)."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      ulid:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      first_name:
                        type: string
                        examples:
                          - Christelle
                      last_name:
                        type: string
                        examples:
                          - Bailey
                      full_name:
                        type: string
                        examples:
                          - 'Christelle Bailey'
                      email:
                        type: string
                        examples:
                          - jdach@example.org
                      email_verified_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      email_verification_excluded:
                        type: boolean
                        examples:
                          - false
                      email_verification_sent_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      phone:
                        type: string
                        examples:
                          - '+12025550104'
                      phone_e164:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      phone_country:
                        type: string
                        examples:
                          - AR
                      phone_type:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      has_whatsapp:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      whatsapp_checked_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      whatsapp_history_synced_until:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      whatsapp_history_exhausted:
                        type: boolean
                        examples:
                          - false
                      avatar_url:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      additional_emails:
                        type: array
                        examples:
                          - []
                      additional_phones:
                        type: array
                        examples:
                          - []
                      company_name:
                        type: string
                        examples:
                          - Runte-Considine
                      contact_type:
                        type: string
                        examples:
                          - lead
                      timezone:
                        type: string
                        examples:
                          - America/Indiana/Tell_City
                      source:
                        type: string
                        examples:
                          - web
                      source_number:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      date_of_birth:
                        type: string
                        examples:
                          - '1985-10-22'
                      dnd_all:
                        type: boolean
                        examples:
                          - false
                      dnd_email:
                        type: boolean
                        examples:
                          - false
                      dnd_sms:
                        type: boolean
                        examples:
                          - false
                      dnd_calls:
                        type: boolean
                        examples:
                          - false
                      dnd_voicemail:
                        type: boolean
                        examples:
                          - false
                      dnd_gmb:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      dnd_fb_messenger:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      dnd_meta:
                        type: object
                        properties: {  }
                      last_activity_at:
                        type: string
                        examples:
                          - '2026-07-31T16:34:00+00:00'
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      owner_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      lead_stage_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
      tags:
        - Contacts
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  description: ''
                  examples:
                    - Ada
                last_name:
                  type:
                    - string
                    - 'null'
                  description: ''
                  examples:
                    - Lovelace
                email:
                  type:
                    - string
                    - 'null'
                  description: ''
                  examples:
                    - ada@example.com
                phone:
                  type:
                    - string
                    - 'null'
                  description: 'E.164 with the country code — `+525555555555`. A local number is only accepted together with `phone_country`; without either the request is rejected. Stored normalised to E.164.'
                  examples:
                    - '+525555555555'
                phone_country:
                  type:
                    - string
                    - 'null'
                  description: 'ISO-3166-1 alpha-2, e.g. `MX`. Only needed when `phone` has no `+` country code; ignored when it does.'
                  examples:
                    - MX
                phone_type:
                  type:
                    - string
                    - 'null'
                  description: 'One of `mobile`, `home`, `work`, `other`.'
                  examples:
                    - mobile
                additional_phones:
                  type: array
                  description: 'Up to 5 extra numbers, same rules as `phone`. They share the single `phone_country`, so send them in E.164 if they are from different countries.'
                  items:
                    type: string
                  examples:
                    -
                      - architecto
                company_name:
                  type:
                    - string
                    - 'null'
                  description: ''
                  examples:
                    - 'Analytical Engines Ltd.'
                company_id:
                  type:
                    - integer
                    - 'null'
                  description: 'The <code>id</code> of an existing record in the companies table.'
                  examples:
                    - 16
                contact_type:
                  type:
                    - string
                    - 'null'
                  description: 'One of `lead`, `customer`, `partner`.'
                  examples:
                    - customer
                lead_stage_id:
                  type:
                    - integer
                    - 'null'
                  description: 'The <code>id</code> of an existing record in the lead_stages table.'
                  examples:
                    - 16
                timezone:
                  type:
                    - string
                    - 'null'
                  description: 'IANA timezone.'
                  examples:
                    - America/Mexico_City
                source:
                  type:
                    - string
                    - 'null'
                  description: ''
                  examples:
                    - web
                date_of_birth:
                  type:
                    - string
                    - 'null'
                  description: 'ISO-8601 date.'
                  examples:
                    - '1815-12-10'
                dnd_all:
                  type:
                    - boolean
                    - 'null'
                  description: ''
                  examples:
                    - false
                dnd_email:
                  type:
                    - boolean
                    - 'null'
                  description: 'Block email for this person. Independent of `dnd_all`, which blocks everything.'
                  examples:
                    - false
                dnd_sms:
                  type:
                    - boolean
                    - 'null'
                  description: 'Block SMS for this person.'
                  examples:
                    - false
                dnd_calls:
                  type:
                    - boolean
                    - 'null'
                  description: 'Block outbound calls for this person.'
                  examples:
                    - false
                dnd_voicemail:
                  type:
                    - boolean
                    - 'null'
                  description: 'Block leaving voicemail for this person.'
                  examples:
                    - false
                dnd_gmb:
                  type:
                    - boolean
                    - 'null'
                  description: 'Block Google Business Messages for this person.'
                  examples:
                    - false
                dnd_fb_messenger:
                  type:
                    - boolean
                    - 'null'
                  description: 'Block Facebook Messenger for this person.'
                  examples:
                    - false
                custom_field_values:
                  type:
                    - object
                    - 'null'
                  description: 'Map of `custom_field_id => value`.'
                  properties: {  }
                  examples:
                    - []
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request PUT \\\n    \"https://klozzo.com/api/contacts/42\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"first_name\\\": \\\"Ada\\\",\n    \\\"last_name\\\": \\\"Lovelace\\\",\n    \\\"email\\\": \\\"ada@example.com\\\",\n    \\\"phone\\\": \\\"+525555555555\\\",\n    \\\"phone_country\\\": \\\"MX\\\",\n    \\\"phone_type\\\": \\\"mobile\\\",\n    \\\"additional_phones\\\": [\n        \\\"architecto\\\"\n    ],\n    \\\"company_name\\\": \\\"Analytical Engines Ltd.\\\",\n    \\\"company_id\\\": 16,\n    \\\"contact_type\\\": \\\"customer\\\",\n    \\\"lead_stage_id\\\": 16,\n    \\\"timezone\\\": \\\"America\\\\/Mexico_City\\\",\n    \\\"source\\\": \\\"web\\\",\n    \\\"date_of_birth\\\": \\\"1815-12-10\\\",\n    \\\"dnd_all\\\": false,\n    \\\"dnd_email\\\": false,\n    \\\"dnd_sms\\\": false,\n    \\\"dnd_calls\\\": false,\n    \\\"dnd_voicemail\\\": false,\n    \\\"dnd_gmb\\\": false,\n    \\\"dnd_fb_messenger\\\": false,\n    \\\"custom_field_values\\\": []\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/42\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"first_name\": \"Ada\",\n    \"last_name\": \"Lovelace\",\n    \"email\": \"ada@example.com\",\n    \"phone\": \"+525555555555\",\n    \"phone_country\": \"MX\",\n    \"phone_type\": \"mobile\",\n    \"additional_phones\": [\n        \"architecto\"\n    ],\n    \"company_name\": \"Analytical Engines Ltd.\",\n    \"company_id\": 16,\n    \"contact_type\": \"customer\",\n    \"lead_stage_id\": 16,\n    \"timezone\": \"America\\/Mexico_City\",\n    \"source\": \"web\",\n    \"date_of_birth\": \"1815-12-10\",\n    \"dnd_all\": false,\n    \"dnd_email\": false,\n    \"dnd_sms\": false,\n    \"dnd_calls\": false,\n    \"dnd_voicemail\": false,\n    \"dnd_gmb\": false,\n    \"dnd_fb_messenger\": false,\n    \"custom_field_values\": []\n};\n\nfetch(url, {\n    method: \"PUT\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/42';\n$response = $client->put(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'first_name' => 'Ada',\n            'last_name' => 'Lovelace',\n            'email' => 'ada@example.com',\n            'phone' => '+525555555555',\n            'phone_country' => 'MX',\n            'phone_type' => 'mobile',\n            'additional_phones' => ['architecto'],\n            'company_name' => 'Analytical Engines Ltd.',\n            'company_id' => 16,\n            'contact_type' => 'customer',\n            'lead_stage_id' => 16,\n            'timezone' => 'America/Mexico_City',\n            'source' => 'web',\n            'date_of_birth' => '1815-12-10',\n            'dnd_all' => false,\n            'dnd_email' => false,\n            'dnd_sms' => false,\n            'dnd_calls' => false,\n            'dnd_voicemail' => false,\n            'dnd_gmb' => false,\n            'dnd_fb_messenger' => false,\n            'custom_field_values' => [],\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/42'\npayload = {\n    \"first_name\": \"Ada\",\n    \"last_name\": \"Lovelace\",\n    \"email\": \"ada@example.com\",\n    \"phone\": \"+525555555555\",\n    \"phone_country\": \"MX\",\n    \"phone_type\": \"mobile\",\n    \"additional_phones\": [\n        \"architecto\"\n    ],\n    \"company_name\": \"Analytical Engines Ltd.\",\n    \"company_id\": 16,\n    \"contact_type\": \"customer\",\n    \"lead_stage_id\": 16,\n    \"timezone\": \"America\\/Mexico_City\",\n    \"source\": \"web\",\n    \"date_of_birth\": \"1815-12-10\",\n    \"dnd_all\": false,\n    \"dnd_email\": false,\n    \"dnd_sms\": false,\n    \"dnd_calls\": false,\n    \"dnd_voicemail\": false,\n    \"dnd_gmb\": false,\n    \"dnd_fb_messenger\": false,\n    \"custom_field_values\": []\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('PUT', url, headers=headers, json=payload)\nresponse.json()"
    delete:
      summary: 'Delete a contact'
      operationId: deleteAContact
      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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Contact deleted.'
                examples:
                  -
                    message: 'Contact deleted.'
        403:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'This action is unauthorized.'
                examples:
                  -
                    message: 'This action is unauthorized.'
      tags:
        - Contacts
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request DELETE \\\n    \"https://klozzo.com/api/contacts/42\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/42\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"DELETE\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/42';\n$response = $client->delete(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/42'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('DELETE', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: id
        description: 'The contact ID.'
        required: true
        schema:
          type: integer
          examples:
            - 42
  /api/contacts/bulk:
    post:
      summary: 'Bulk action on contacts'
      operationId: bulkActionOnContacts
      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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Bulk action completed.'
                examples:
                  -
                    message: 'Bulk action completed.'
        422:
          description: 'invalid action'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'The selected action is invalid.'
                  errors:
                    type: object
                    properties:
                      action:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - 'The selected action is invalid.'
                examples:
                  -
                    message: 'The selected action is invalid.'
                    errors:
                      action:
                        - 'The selected action is invalid.'
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: 'Action to perform. Currently only `delete`.'
                  examples:
                    - delete
                ids:
                  type: array
                  description: 'IDs of contacts to act on (min 1).'
                  items:
                    type: integer
                  examples:
                    -
                      - 16
              required:
                - action
                - ids
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/contacts/bulk\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"action\\\": \\\"delete\\\",\n    \\\"ids\\\": [\n        16\n    ]\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/bulk\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"action\": \"delete\",\n    \"ids\": [\n        16\n    ]\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/bulk';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'action' => 'delete',\n            'ids' => [16],\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/bulk'\npayload = {\n    \"action\": \"delete\",\n    \"ids\": [\n        16\n    ]\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  '/api/contacts/{contact_id}/verify-email':
    post:
      summary: "Check whether a contact's email really exists"
      operationId: checkWhetherAContactsEmailReallyExists
      description: "Queues a deliverability check against the configured verification\nprovider and answers `202` straight away — 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."
      parameters: []
      responses:
        202:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Email verification queued.'
                  contact_id:
                    type: integer
                    examples:
                      - 42
                  status:
                    type: string
                    examples:
                      - unverified
                examples:
                  -
                    message: 'Email verification queued.'
                    contact_id: 42
                    status: unverified
        403:
          description: 'Read-only role'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'This action is unauthorized.'
                examples:
                  -
                    message: 'This action is unauthorized.'
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'The contact has no email'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Contact has no email to verify.'
                      errors:
                        type: object
                        properties:
                          email:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Contact has no email to verify.'
                    examples:
                      -
                        message: 'Contact has no email to verify.'
                        errors:
                          email:
                            - 'Contact has no email to verify.'
                  -
                    description: 'The contact is excluded from verification'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Contact is excluded from email verification.'
                      errors:
                        type: object
                        properties:
                          email:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Contact is excluded from email verification.'
                    examples:
                      -
                        message: 'Contact is excluded from email verification.'
                        errors:
                          email:
                            - 'Contact is excluded from email verification.'
      tags:
        - Contacts
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                driver:
                  type:
                    - string
                    - 'null'
                  description: 'Force a specific provider instead of the account default. One of `zerobounce`, `mailgun`, `ses`, `null`.'
                  examples:
                    - zerobounce
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/contacts/42/verify-email\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"driver\\\": \\\"zerobounce\\\"\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/42/verify-email\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"driver\": \"zerobounce\"\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/42/verify-email';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'driver' => 'zerobounce',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/42/verify-email'\npayload = {\n    \"driver\": \"zerobounce\"\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
    parameters:
      -
        in: path
        name: contact_id
        description: "The contact's id."
        required: true
        schema:
          type: string
          examples:
            - '42'
  '/api/contacts/{contact_id}/owner':
    patch:
      summary: 'Reassign contact owner'
      operationId: reassignContactOwner
      description: "Transfers ownership of a contact to a different user. Pass `owner_id = null`\nto unassign. Requires the `reassignOwner` policy."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      ulid:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      first_name:
                        type: string
                        examples:
                          - Audra
                      last_name:
                        type: string
                        examples:
                          - Crooks
                      full_name:
                        type: string
                        examples:
                          - 'Audra Crooks'
                      email:
                        type: string
                        examples:
                          - rempel.chadrick@example.org
                      email_verified_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      email_verification_excluded:
                        type: boolean
                        examples:
                          - false
                      email_verification_sent_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      phone:
                        type: string
                        examples:
                          - '+12025550105'
                      phone_e164:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      phone_country:
                        type: string
                        examples:
                          - CO
                      phone_type:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      has_whatsapp:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      whatsapp_checked_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      whatsapp_history_synced_until:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      whatsapp_history_exhausted:
                        type: boolean
                        examples:
                          - false
                      avatar_url:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      additional_emails:
                        type: array
                        examples:
                          - []
                      additional_phones:
                        type: array
                        examples:
                          - []
                      company_name:
                        type: string
                        examples:
                          - 'Gaylord and Sons'
                      contact_type:
                        type: string
                        examples:
                          - customer
                      timezone:
                        type: string
                        examples:
                          - America/Eirunepe
                      source:
                        type: string
                        examples:
                          - manual
                      source_number:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      date_of_birth:
                        type: string
                        examples:
                          - '1991-08-13'
                      dnd_all:
                        type: boolean
                        examples:
                          - false
                      dnd_email:
                        type: boolean
                        examples:
                          - false
                      dnd_sms:
                        type: boolean
                        examples:
                          - false
                      dnd_calls:
                        type: boolean
                        examples:
                          - false
                      dnd_voicemail:
                        type: boolean
                        examples:
                          - false
                      dnd_gmb:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      dnd_fb_messenger:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      dnd_meta:
                        type: object
                        properties: {  }
                      last_activity_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      owner_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      lead_stage_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
      tags:
        - Contacts
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                owner_id:
                  type:
                    - integer
                    - 'null'
                  description: 'User ID of the new owner. Set to `null` to unassign.'
                  examples:
                    - 7
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request PATCH \\\n    \"https://klozzo.com/api/contacts/42/owner\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"owner_id\\\": 7\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/42/owner\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"owner_id\": 7\n};\n\nfetch(url, {\n    method: \"PATCH\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/42/owner';\n$response = $client->patch(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'owner_id' => 7,\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/42/owner'\npayload = {\n    \"owner_id\": 7\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('PATCH', url, headers=headers, json=payload)\nresponse.json()"
    parameters:
      -
        in: path
        name: contact_id
        description: 'The contact ID.'
        required: true
        schema:
          type: integer
          examples:
            - 42
  '/api/contacts/{contact_id}/followers':
    post:
      summary: 'Add a follower to a contact'
      operationId: addAFollowerToAContact
      description: "Followers receive notifications about activity on the contact. Idempotent:\nadding an existing follower is a no-op."
      parameters: []
      responses:
        201:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Follower added.'
                  followers:
                    type: array
                    items:
                      type: integer
                    examples:
                      -
                        - 7
                        - 12
                examples:
                  -
                    message: 'Follower added.'
                    followers:
                      - 7
                      - 12
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: integer
                  description: 'ID of the user to add as follower.'
                  examples:
                    - 7
              required:
                - user_id
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/contacts/42/followers\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"user_id\\\": 7\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/42/followers\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"user_id\": 7\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/42/followers';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'user_id' => 7,\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/42/followers'\npayload = {\n    \"user_id\": 7\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
    parameters:
      -
        in: path
        name: contact_id
        description: 'The contact ID.'
        required: true
        schema:
          type: integer
          examples:
            - 42
  '/api/contacts/{contact_id}/followers/{user}':
    delete:
      summary: 'Remove a follower from a contact'
      operationId: removeAFollowerFromAContact
      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 — removing somebody who was not following answers `200` all the\nsame, so a sync that cannot remember what it already did is safe."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Follower removed.'
                  followers:
                    type: array
                    items:
                      type: integer
                    examples:
                      -
                        - 12
                examples:
                  -
                    message: 'Follower removed.'
                    followers:
                      - 12
      tags:
        - Contacts
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request DELETE \\\n    \"https://klozzo.com/api/contacts/42/followers/7\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/42/followers/7\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"DELETE\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/42/followers/7';\n$response = $client->delete(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/42/followers/7'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('DELETE', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: contact_id
        description: 'The contact ID.'
        required: true
        schema:
          type: integer
          examples:
            - 42
      -
        in: path
        name: user
        description: 'ID of the user to remove.'
        required: true
        schema:
          type: integer
          examples:
            - 7
  '/api/contacts/{contact_id}/dnd-settings':
    get:
      summary: "List a contact's do-not-disturb settings"
      operationId: listAContactsDoNotDisturbSettings
      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 — 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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          examples:
                            - 9
                        contact_id:
                          type: integer
                          examples:
                            - 42
                        channel:
                          type: string
                          examples:
                            - sms
                        enabled:
                          type: boolean
                          examples:
                            - true
                        scheduled_until:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        set_by:
                          type: integer
                          examples:
                            - 3
                        set_at:
                          type: string
                          examples:
                            - '2026-08-23T17:04:00+00:00'
                        is_active:
                          type: boolean
                          examples:
                            - true
                    examples:
                      -
                        -
                          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
                examples:
                  -
                    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
        404:
          description: 'Not yours, or does not exist'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No query results for model [App\Models\Contact].'
                examples:
                  -
                    message: 'No query results for model [App\Models\Contact].'
      tags:
        - Contacts
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/contacts/42/dnd-settings\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/42/dnd-settings\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/42/dnd-settings';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/42/dnd-settings'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    post:
      summary: 'Block a channel for a contact'
      operationId: blockAChannelForAContact
      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 — 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 — consent decisions have to be provable."
      parameters: []
      responses:
        201:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        examples:
                          - 9
                      contact_id:
                        type: integer
                        examples:
                          - 42
                      channel:
                        type: string
                        examples:
                          - sms
                      enabled:
                        type: boolean
                        examples:
                          - true
                      scheduled_until:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      set_by:
                        type: integer
                        examples:
                          - 3
                      set_at:
                        type: string
                        examples:
                          - '2026-08-23T17:04:00+00:00'
                      is_active:
                        type: boolean
                        examples:
                          - true
                examples:
                  -
                    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
        403:
          description: 'Role without consent permissions'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'This action is unauthorized.'
                examples:
                  -
                    message: 'This action is unauthorized.'
        422:
          description: 'Unknown channel'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'The selected channel is invalid.'
                  errors:
                    type: object
                    properties:
                      channel:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - 'The selected channel is invalid.'
                examples:
                  -
                    message: 'The selected channel is invalid.'
                    errors:
                      channel:
                        - 'The selected channel is invalid.'
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                channel:
                  type: string
                  description: ''
                  examples:
                    - architecto
                enabled:
                  type: boolean
                  description: ''
                  examples:
                    - true
                scheduled_until:
                  type:
                    - string
                    - 'null'
                  description: 'Must be a valid date. Must be a date after <code>now</code>.'
                  examples:
                    - '2052-09-18'
              required:
                - channel
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/contacts/42/dnd-settings\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"channel\\\": \\\"architecto\\\",\n    \\\"enabled\\\": true,\n    \\\"scheduled_until\\\": \\\"2052-09-18\\\"\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/42/dnd-settings\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"channel\": \"architecto\",\n    \"enabled\": true,\n    \"scheduled_until\": \"2052-09-18\"\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/42/dnd-settings';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'channel' => 'architecto',\n            'enabled' => true,\n            'scheduled_until' => '2052-09-18',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/42/dnd-settings'\npayload = {\n    \"channel\": \"architecto\",\n    \"enabled\": true,\n    \"scheduled_until\": \"2052-09-18\"\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
    parameters:
      -
        in: path
        name: contact_id
        description: "The contact's id."
        required: true
        schema:
          type: string
          examples:
            - '42'
  '/api/contacts/{contact_id}/dnd-settings/{dndSetting_id}':
    delete:
      summary: 'Unblock a channel for a contact'
      operationId: unblockAChannelForAContact
      description: "Removes the setting, which means the channel is open again. Use it when\nsomebody opts back in — 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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'DND setting removed.'
                examples:
                  -
                    message: 'DND setting removed.'
        403:
          description: 'Role without consent permissions'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'This action is unauthorized.'
                examples:
                  -
                    message: 'This action is unauthorized.'
        404:
          description: 'The setting belongs to another contact'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Not Found'
                examples:
                  -
                    message: 'Not Found'
      tags:
        - Contacts
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request DELETE \\\n    \"https://klozzo.com/api/contacts/42/dnd-settings/9\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/42/dnd-settings/9\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"DELETE\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/42/dnd-settings/9';\n$response = $client->delete(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/42/dnd-settings/9'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('DELETE', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: contact_id
        description: "The contact's id."
        required: true
        schema:
          type: string
          examples:
            - '42'
      -
        in: path
        name: dndSetting_id
        description: "The setting's id, from the list endpoint."
        required: true
        schema:
          type: string
          examples:
            - '9'
  '/api/contacts/{contact_id}/custom-field-values':
    get:
      summary: "Read a contact's custom field values"
      operationId: readAContactsCustomFieldValues
      description: "Returns the custom field values of one contact as a flat object keyed by\nthe field's `key` — 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)."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      presupuesto_mensual:
                        type: string
                        examples:
                          - '25000'
                      canal_preferido:
                        type: string
                        examples:
                          - whatsapp
                examples:
                  -
                    data:
                      presupuesto_mensual: '25000'
                      canal_preferido: whatsapp
        404:
          description: 'Not visible from your location'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No query results for model [App\Models\Contact].'
                examples:
                  -
                    message: 'No query results for model [App\Models\Contact].'
      tags:
        - Contacts
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/contacts/42/custom-field-values\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/42/custom-field-values\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/42/custom-field-values';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/42/custom-field-values'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    put:
      summary: "Write a contact's custom field values"
      operationId: writeAContactsCustomFieldValues
      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** —\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 — a date field rejects\n`\"mañana\"`, 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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Custom field values synced.'
                examples:
                  -
                    message: 'Custom field values synced.'
        403:
          description: 'Read-only role'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'This action is unauthorized.'
                examples:
                  -
                    message: 'This action is unauthorized.'
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'A key that does not exist'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'El campo personalizado «presupesto» no existe o no está disponible en tu cuenta.'
                      errors:
                        type: object
                        properties:
                          values.presupesto:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'El campo personalizado «presupesto» no existe o no está disponible en tu cuenta.'
                    examples:
                      -
                        message: 'El campo personalizado «presupesto» no existe o no está disponible en tu cuenta.'
                        errors:
                          values.presupesto:
                            - 'El campo personalizado «presupesto» no existe o no está disponible en tu cuenta.'
                  -
                    description: "A value the field's type rejects"
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'The values.fecha_de_alta is not a valid date.'
                      errors:
                        type: object
                        properties:
                          values.fecha_de_alta:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'The values.fecha_de_alta is not a valid date.'
                    examples:
                      -
                        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.'
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                values:
                  type: object
                  description: 'The values to set, keyed by field.'
                  properties: {  }
                  examples:
                    -
                      presupuesto_mensual: '25000'
              required:
                - values
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request PUT \\\n    \"https://klozzo.com/api/contacts/42/custom-field-values\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"values\\\": {\n        \\\"presupuesto_mensual\\\": \\\"25000\\\"\n    }\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/42/custom-field-values\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"values\": {\n        \"presupuesto_mensual\": \"25000\"\n    }\n};\n\nfetch(url, {\n    method: \"PUT\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/42/custom-field-values';\n$response = $client->put(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'values' => ['presupuesto_mensual' => '25000'],\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/42/custom-field-values'\npayload = {\n    \"values\": {\n        \"presupuesto_mensual\": \"25000\"\n    }\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('PUT', url, headers=headers, json=payload)\nresponse.json()"
    parameters:
      -
        in: path
        name: contact_id
        description: "The contact's id."
        required: true
        schema:
          type: string
          examples:
            - '42'
  '/api/contacts/{contact_id}/activity':
    get:
      summary: "List a contact's activity timeline"
      operationId: listAContactsActivityTimeline
      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 — pass it more than\nonce for several. The payload shape depends on the event type, so read\n`event_type` before reaching into `payload`."
      parameters:
        -
          in: query
          name: per_page
          description: 'Rows per page. Default 25, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
          required: false
          schema:
            type: integer
            description: 'Rows per page. Default 25, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
            examples:
              - 25
        -
          in: query
          name: cursor
          description: 'The `next_cursor` from the previous response.'
          required: false
          schema:
            type: string
            description: 'The `next_cursor` from the previous response.'
            examples:
              - eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0
        -
          in: query
          name: event_type
          description: 'Only these event types.'
          required: false
          schema:
            type: array
            description: 'Only these event types.'
            items:
              type: string
            examples:
              -
                - page_visited
                - form_submitted
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          examples:
                            - 881
                        event_type:
                          type: string
                          examples:
                            - form_submitted
                        subject_type:
                          type: string
                          examples:
                            - contact
                        subject_id:
                          type: integer
                          examples:
                            - 42
                        actor_type:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        actor_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        location_id:
                          type: integer
                          examples:
                            - 3
                        payload:
                          type: object
                          properties:
                            form_id:
                              type: string
                              examples:
                                - newsletter
                            utm_source:
                              type: string
                              examples:
                                - adwords
                        occurred_at:
                          type: string
                          examples:
                            - '2026-08-23T17:04:00+00:00'
                    examples:
                      -
                        -
                          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:
                    type: string
                    examples:
                      - eyJpZCI6ODgxfQ
                  prev_cursor:
                    type:
                      - string
                      - 'null'
                    examples:
                      - null
                examples:
                  -
                    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
        404:
          description: 'Not visible from your location'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No query results for model [App\Models\Contact].'
                examples:
                  -
                    message: 'No query results for model [App\Models\Contact].'
      tags:
        - Contacts
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/contacts/42/activity?per_page=25&cursor=eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0&event_type[]=page_visited&event_type[]=form_submitted\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/42/activity\"\n);\n\nconst params = {\n    \"per_page\": \"25\",\n    \"cursor\": \"eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0\",\n    \"event_type[0]\": \"page_visited\",\n    \"event_type[1]\": \"form_submitted\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/42/activity';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'per_page' => '25',\n            'cursor' => 'eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0',\n            'event_type[0]' => 'page_visited',\n            'event_type[1]' => 'form_submitted',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/42/activity'\nparams = {\n  'per_page': '25',\n  'cursor': 'eyJpZCI6MTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0',\n  'event_type[0]': 'page_visited',\n  'event_type[1]': 'form_submitted',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers, params=params)\nresponse.json()"
    parameters:
      -
        in: path
        name: contact_id
        description: "The contact's id."
        required: true
        schema:
          type: string
          examples:
            - '42'
  /api/custom-fields:
    get:
      summary: 'List custom fields'
      operationId: listCustomFields
      description: "Returns all custom fields for the authenticated user's location, ordered by\n`sort_order` then alphabetically."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        key:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        label:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        name:
                          type: string
                          examples:
                            - quidem
                        type:
                          type: string
                          examples:
                            - text
                        write_policy:
                          type: string
                          examples:
                            - fill_if_empty
                        options:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        default_value:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        is_required:
                          type: boolean
                          examples:
                            - false
                        sort_order:
                          type: integer
                          examples:
                            - 6
                        created_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        updated_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                    examples:
                      -
                        -
                          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
                examples:
                  -
                    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
      tags:
        - 'Custom Fields'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/custom-fields\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/custom-fields\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/custom-fields';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/custom-fields'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    post:
      summary: 'Create a custom field'
      operationId: createACustomField
      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** — 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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      key:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      label:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      name:
                        type: string
                        examples:
                          - eius
                      type:
                        type: string
                        examples:
                          - phone
                      write_policy:
                        type: string
                        examples:
                          - fill_if_empty
                      options:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      default_value:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      is_required:
                        type: boolean
                        examples:
                          - false
                      sort_order:
                        type: integer
                        examples:
                          - 10
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
      tags:
        - 'Custom Fields'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Display name (max 255).'
                  examples:
                    - 'Lifecycle stage'
                key:
                  type: string
                  description: 'Stable, immutable identifier used by the API (lowercase a-z, 0-9, _). Derived from `name` if omitted.'
                  examples:
                    - lifecycle_stage
                type:
                  type: string
                  description: 'One of `text`, `number`, `date`, `dropdown`, `checkbox`, `url`, `phone`, `email`.'
                  examples:
                    - dropdown
                write_policy:
                  type:
                    - string
                    - 'null'
                  description: 'What happens when a new value arrives for this field. One of `fill_if_empty` (default — only fills a blank, never overwrites), `last_write_wins` (newest value always wins), `immutable` (written once, then locked).'
                  examples:
                    - fill_if_empty
                options:
                  type: array
                  description: 'Required when `type=dropdown`; the available choices.'
                  items:
                    type: string
                  examples:
                    -
                      - architecto
                default_value:
                  type:
                    - string
                    - 'null'
                  description: 'Default applied to new contacts.'
                  examples:
                    - trial
                is_required:
                  type:
                    - boolean
                    - 'null'
                  description: 'Whether this field must be filled.'
                  examples:
                    - false
                sort_order:
                  type:
                    - integer
                    - 'null'
                  description: 'Display order in forms (low values first).'
                  examples:
                    - 0
              required:
                - name
                - type
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/custom-fields\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"name\\\": \\\"Lifecycle stage\\\",\n    \\\"key\\\": \\\"lifecycle_stage\\\",\n    \\\"type\\\": \\\"dropdown\\\",\n    \\\"write_policy\\\": \\\"fill_if_empty\\\",\n    \\\"options\\\": [\n        \\\"architecto\\\"\n    ],\n    \\\"default_value\\\": \\\"trial\\\",\n    \\\"is_required\\\": false,\n    \\\"sort_order\\\": 0\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/custom-fields\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"name\": \"Lifecycle stage\",\n    \"key\": \"lifecycle_stage\",\n    \"type\": \"dropdown\",\n    \"write_policy\": \"fill_if_empty\",\n    \"options\": [\n        \"architecto\"\n    ],\n    \"default_value\": \"trial\",\n    \"is_required\": false,\n    \"sort_order\": 0\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/custom-fields';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'name' => 'Lifecycle stage',\n            'key' => 'lifecycle_stage',\n            'type' => 'dropdown',\n            'write_policy' => 'fill_if_empty',\n            'options' => ['architecto'],\n            'default_value' => 'trial',\n            'is_required' => false,\n            'sort_order' => 0,\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/custom-fields'\npayload = {\n    \"name\": \"Lifecycle stage\",\n    \"key\": \"lifecycle_stage\",\n    \"type\": \"dropdown\",\n    \"write_policy\": \"fill_if_empty\",\n    \"options\": [\n        \"architecto\"\n    ],\n    \"default_value\": \"trial\",\n    \"is_required\": false,\n    \"sort_order\": 0\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  '/api/custom-fields/{uuid}':
    get:
      summary: 'Fetch a custom field'
      operationId: fetchACustomField
      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 — nine times out of ten the answer is in\n`write_policy`, not in your payload."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      key:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      label:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      name:
                        type: string
                        examples:
                          - nostrum
                      type:
                        type: string
                        examples:
                          - number
                      write_policy:
                        type: string
                        examples:
                          - fill_if_empty
                      options:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      default_value:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      is_required:
                        type: boolean
                        examples:
                          - false
                      sort_order:
                        type: integer
                        examples:
                          - 6
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        404:
          description: 'Does not exist, or belongs to another location'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No query results for model.'
                examples:
                  -
                    message: 'No query results for model.'
      tags:
        - 'Custom Fields'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/custom-fields/9\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/custom-fields/9\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/custom-fields/9';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/custom-fields/9'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    put:
      summary: 'Update a custom field'
      operationId: updateACustomField
      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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      key:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      label:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      name:
                        type: string
                        examples:
                          - et
                      type:
                        type: string
                        examples:
                          - url
                      write_policy:
                        type: string
                        examples:
                          - fill_if_empty
                      options:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      default_value:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      is_required:
                        type: boolean
                        examples:
                          - false
                      sort_order:
                        type: integer
                        examples:
                          - 3
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'A type that does not exist'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Type no es una opción válida.'
                      errors:
                        type: object
                        properties:
                          type:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Type no es una opción válida.'
                    examples:
                      -
                        message: 'Type no es una opción válida.'
                        errors:
                          type:
                            - 'Type no es una opción válida.'
                  -
                    description: 'A dropdown with no options'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Falta options cuando type es dropdown.'
                      errors:
                        type: object
                        properties:
                          options:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Falta options cuando type es dropdown.'
                    examples:
                      -
                        message: 'Falta options cuando type es dropdown.'
                        errors:
                          options:
                            - 'Falta options cuando type es dropdown.'
                  -
                    description: 'A key already used in this location'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'El valor de key ya está en uso.'
                      errors:
                        type: object
                        properties:
                          key:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'El valor de key ya está en uso.'
                    examples:
                      -
                        message: 'El valor de key ya está en uso.'
                        errors:
                          key:
                            - 'El valor de key ya está en uso.'
      tags:
        - 'Custom Fields'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Display name.'
                  examples:
                    - 'Lifecycle stage'
                label:
                  type:
                    - string
                    - 'null'
                  description: 'Must not be greater than 255 characters.'
                  examples:
                    - 'n'
                type:
                  type: string
                  description: 'One of the supported types (see create).'
                  examples:
                    - architecto
                write_policy:
                  type: string
                  description: ''
                  enum:
                    - immutable
                    - fill_if_empty
                    - last_write_wins
                  examples:
                    - last_write_wins
                options:
                  type: array
                  description: 'Required when `type=dropdown`.'
                  items:
                    type: string
                  examples:
                    -
                      - architecto
                default_value:
                  type:
                    - string
                    - 'null'
                  description: 'Default applied to new contacts.'
                  examples:
                    - architecto
                is_required:
                  type:
                    - boolean
                    - 'null'
                  description: 'Whether a contact form refuses to save without this field. Does not apply retroactively to contacts that already exist.'
                  examples:
                    - false
                sort_order:
                  type:
                    - integer
                    - 'null'
                  description: 'Where the field sits in forms; low values first.'
                  examples:
                    - 0
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request PUT \\\n    \"https://klozzo.com/api/custom-fields/9\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"name\\\": \\\"Lifecycle stage\\\",\n    \\\"label\\\": \\\"n\\\",\n    \\\"type\\\": \\\"architecto\\\",\n    \\\"write_policy\\\": \\\"last_write_wins\\\",\n    \\\"options\\\": [\n        \\\"architecto\\\"\n    ],\n    \\\"default_value\\\": \\\"architecto\\\",\n    \\\"is_required\\\": false,\n    \\\"sort_order\\\": 0\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/custom-fields/9\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"name\": \"Lifecycle stage\",\n    \"label\": \"n\",\n    \"type\": \"architecto\",\n    \"write_policy\": \"last_write_wins\",\n    \"options\": [\n        \"architecto\"\n    ],\n    \"default_value\": \"architecto\",\n    \"is_required\": false,\n    \"sort_order\": 0\n};\n\nfetch(url, {\n    method: \"PUT\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/custom-fields/9';\n$response = $client->put(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'name' => 'Lifecycle stage',\n            'label' => 'n',\n            'type' => 'architecto',\n            'write_policy' => 'last_write_wins',\n            'options' => ['architecto'],\n            'default_value' => 'architecto',\n            'is_required' => false,\n            'sort_order' => 0,\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/custom-fields/9'\npayload = {\n    \"name\": \"Lifecycle stage\",\n    \"label\": \"n\",\n    \"type\": \"architecto\",\n    \"write_policy\": \"last_write_wins\",\n    \"options\": [\n        \"architecto\"\n    ],\n    \"default_value\": \"architecto\",\n    \"is_required\": false,\n    \"sort_order\": 0\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('PUT', url, headers=headers, json=payload)\nresponse.json()"
    delete:
      summary: 'Delete a custom field'
      operationId: deleteACustomField
      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)."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Custom field deleted.'
                examples:
                  -
                    message: 'Custom field deleted.'
      tags:
        - 'Custom Fields'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request DELETE \\\n    \"https://klozzo.com/api/custom-fields/9\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/custom-fields/9\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"DELETE\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/custom-fields/9';\n$response = $client->delete(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/custom-fields/9'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('DELETE', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: uuid
        description: 'Custom field ID.'
        required: true
        schema:
          type: integer
          examples:
            - 9
  /api/tags:
    get:
      summary: 'List tags'
      operationId: listTags
      description: "Returns all tags owned by the authenticated user, sorted alphabetically.\nEach tag includes the count of associated contacts."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        name:
                          type: string
                          examples:
                            - aut
                        slug:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        color:
                          type: string
                          examples:
                            - '#a11e59'
                        location_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        created_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        updated_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                    examples:
                      -
                        -
                          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
                examples:
                  -
                    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
      tags:
        - Tags
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/tags\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/tags\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/tags';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/tags'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    post:
      summary: 'Create a tag'
      operationId: createATag
      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 — 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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      name:
                        type: string
                        examples:
                          - nihil
                      slug:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      color:
                        type: string
                        examples:
                          - '#c8a15d'
                      location_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    data:
                      id: null
                      name: nihil
                      slug: null
                      color: '#c8a15d'
                      location_id: null
                      created_at: null
                      updated_at: null
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'A colour that is not a hex code'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Color no tiene un formato válido.'
                      errors:
                        type: object
                        properties:
                          color:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Color no tiene un formato válido.'
                    examples:
                      -
                        message: 'Color no tiene un formato válido.'
                        errors:
                          color:
                            - 'Color no tiene un formato válido.'
                  -
                    description: 'A name already used in this location'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'El valor de name ya está en uso.'
                      errors:
                        type: object
                        properties:
                          name:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'El valor de name ya está en uso.'
                    examples:
                      -
                        message: 'El valor de name ya está en uso.'
                        errors:
                          name:
                            - 'El valor de name ya está en uso.'
      tags:
        - Tags
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Tag name (max 255).'
                  examples:
                    - VIP
                color:
                  type:
                    - string
                    - 'null'
                  description: 'Hex color including the `#` prefix.'
                  examples:
                    - '#ff6b35'
              required:
                - name
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/tags\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"name\\\": \\\"VIP\\\",\n    \\\"color\\\": \\\"#ff6b35\\\"\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/tags\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"name\": \"VIP\",\n    \"color\": \"#ff6b35\"\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/tags';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'name' => 'VIP',\n            'color' => '#ff6b35',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/tags'\npayload = {\n    \"name\": \"VIP\",\n    \"color\": \"#ff6b35\"\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  '/api/tags/{id}':
    get:
      summary: 'Fetch a tag'
      operationId: fetchATag
      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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      name:
                        type: string
                        examples:
                          - adipisci
                      slug:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      color:
                        type: string
                        examples:
                          - '#f76df4'
                      location_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    data:
                      id: null
                      name: adipisci
                      slug: null
                      color: '#f76df4'
                      location_id: null
                      created_at: null
                      updated_at: null
        404:
          description: 'Does not exist, or belongs to another location'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No query results for model.'
                examples:
                  -
                    message: 'No query results for model.'
      tags:
        - Tags
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/tags/3\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/tags/3\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/tags/3';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/tags/3'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    put:
      summary: 'Update a tag'
      operationId: updateATag
      description: "Updates a tag's name or colour by id. **Every contact carrying the tag sees\nthe new name immediately** — a tag is one row, not a copy per contact — so\nrenaming is how you fix a typo, never how you split a group in two."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      name:
                        type: string
                        examples:
                          - accusantium
                      slug:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      color:
                        type: string
                        examples:
                          - '#902510'
                      location_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    data:
                      id: null
                      name: accusantium
                      slug: null
                      color: '#902510'
                      location_id: null
                      created_at: null
                      updated_at: null
      tags:
        - Tags
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Tag name (max 255).'
                  examples:
                    - 'VIP Customer'
                color:
                  type: string
                  description: 'Hex color including the `#` prefix.'
                  examples:
                    - '#ff6b35'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request PUT \\\n    \"https://klozzo.com/api/tags/3\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"name\\\": \\\"VIP Customer\\\",\n    \\\"color\\\": \\\"#ff6b35\\\"\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/tags/3\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"name\": \"VIP Customer\",\n    \"color\": \"#ff6b35\"\n};\n\nfetch(url, {\n    method: \"PUT\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/tags/3';\n$response = $client->put(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'name' => 'VIP Customer',\n            'color' => '#ff6b35',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/tags/3'\npayload = {\n    \"name\": \"VIP Customer\",\n    \"color\": \"#ff6b35\"\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('PUT', url, headers=headers, json=payload)\nresponse.json()"
    delete:
      summary: 'Delete a tag'
      operationId: deleteATag
      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."
      parameters:
        -
          in: query
          name: force
          description: 'Detach from contacts and delete anyway.'
          required: false
          schema:
            type: boolean
            description: 'Detach from contacts and delete anyway.'
            examples:
              - true
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Tag deleted.'
                examples:
                  -
                    message: 'Tag deleted.'
        409:
          description: 'tag in use'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Tag is in use.'
                  contacts_count:
                    type: integer
                    examples:
                      - 12
                  hint:
                    type: string
                    examples:
                      - 'Pass force=true to detach and delete.'
                examples:
                  -
                    message: 'Tag is in use.'
                    contacts_count: 12
                    hint: 'Pass force=true to detach and delete.'
      tags:
        - Tags
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request DELETE \\\n    \"https://klozzo.com/api/tags/3?force=1\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/tags/3\"\n);\n\nconst params = {\n    \"force\": \"1\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"DELETE\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/tags/3';\n$response = $client->delete(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'force' => '1',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/tags/3'\nparams = {\n  'force': '1',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('DELETE', url, headers=headers, params=params)\nresponse.json()"
    parameters:
      -
        in: path
        name: id
        description: 'Tag ID.'
        required: true
        schema:
          type: integer
          examples:
            - 3
  /api/smart-lists:
    get:
      summary: 'List smart lists'
      operationId: listSmartLists
      description: "Returns smart lists visible to the authenticated user, ordered by `sort_order`\nthen alphabetically by name."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        location_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        user_id:
                          type: integer
                          examples:
                            - 3765
                        name:
                          type: string
                          examples:
                            - 'aut adipisci'
                        filters:
                          type: array
                          items:
                            type: object
                            properties:
                              field:
                                type: string
                                examples:
                                  - contact_type
                              operator:
                                type: string
                                examples:
                                  - '='
                              value:
                                type: string
                                examples:
                                  - lead
                          examples:
                            -
                              -
                                field: contact_type
                                operator: '='
                                value: lead
                        sort:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        sort_order:
                          type: integer
                          examples:
                            - 2
                        is_shared:
                          type: boolean
                          examples:
                            - false
                        is_default:
                          type: boolean
                          examples:
                            - false
                        created_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        updated_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                    examples:
                      -
                        -
                          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
                examples:
                  -
                    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
      tags:
        - 'Smart Lists'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/smart-lists\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/smart-lists\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/smart-lists';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/smart-lists'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    post:
      summary: 'Create a smart list'
      operationId: createASmartList
      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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      location_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      user_id:
                        type: integer
                        examples:
                          - 3767
                      name:
                        type: string
                        examples:
                          - 'architecto eius'
                      filters:
                        type: array
                        items:
                          type: object
                          properties:
                            field:
                              type: string
                              examples:
                                - contact_type
                            operator:
                              type: string
                              examples:
                                - '='
                            value:
                              type: string
                              examples:
                                - lead
                        examples:
                          -
                            -
                              field: contact_type
                              operator: '='
                              value: lead
                      sort:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      sort_order:
                        type: integer
                        examples:
                          - 0
                      is_shared:
                        type: boolean
                        examples:
                          - false
                      is_default:
                        type: boolean
                        examples:
                          - false
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'A list with no rule'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Falta filters.'
                      errors:
                        type: object
                        properties:
                          filters:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Falta filters.'
                    examples:
                      -
                        message: 'Falta filters.'
                        errors:
                          filters:
                            - 'Falta filters.'
                  -
                    description: 'A clause missing its operator'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Falta filters.0.operator.'
                      errors:
                        type: object
                        properties:
                          filters.0.operator:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Falta filters.0.operator.'
                    examples:
                      -
                        message: 'Falta filters.0.operator.'
                        errors:
                          filters.0.operator:
                            - 'Falta filters.0.operator.'
      tags:
        - 'Smart Lists'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Display name (max 255).'
                  examples:
                    - 'Hot leads, last 7 days'
                filters:
                  type: array
                  description: 'Filter clauses. Each clause: `{field, operator, value}`. Min 1.'
                  items:
                    type: object
                    properties:
                      field:
                        type: string
                        description: 'Field name.'
                        examples:
                          - contact_type
                      operator:
                        type: string
                        description: 'Operator (e.g. `eq`, `ne`, `in`, `gt`, `like`).'
                        examples:
                          - eq
                      value:
                        type: string
                        description: 'Value to compare against. A string for most operators, a list for `in`, a date for the date ones — whatever the field takes.'
                        examples:
                          - lead
                    required:
                      - field
                      - operator
                      - value
                  examples:
                    -
                      - []
                sort:
                  type:
                    - object
                    - 'null'
                  description: 'Default sort. Shape: `{field, direction}`.'
                  properties:
                    field:
                      type: string
                      description: 'Field to sort by.'
                      examples:
                        - created_at
                    direction:
                      type: string
                      description: 'Either `asc` or `desc`.'
                      examples:
                        - desc
                  examples:
                    - []
                sort_order:
                  type:
                    - integer
                    - 'null'
                  description: 'Display order in sidebar (low values first).'
                  examples:
                    - 0
                is_shared:
                  type: boolean
                  description: 'Share across location.'
                  examples:
                    - false
                is_default:
                  type: boolean
                  description: "Mark as the user's default list."
                  examples:
                    - false
              required:
                - name
                - filters
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/smart-lists\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"name\\\": \\\"Hot leads, last 7 days\\\",\n    \\\"filters\\\": [\n        {\n            \\\"field\\\": \\\"contact_type\\\",\n            \\\"operator\\\": \\\"eq\\\",\n            \\\"value\\\": \\\"lead\\\"\n        }\n    ],\n    \\\"sort\\\": {\n        \\\"field\\\": \\\"created_at\\\",\n        \\\"direction\\\": \\\"desc\\\"\n    },\n    \\\"sort_order\\\": 0,\n    \\\"is_shared\\\": false,\n    \\\"is_default\\\": false\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/smart-lists\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"name\": \"Hot leads, last 7 days\",\n    \"filters\": [\n        {\n            \"field\": \"contact_type\",\n            \"operator\": \"eq\",\n            \"value\": \"lead\"\n        }\n    ],\n    \"sort\": {\n        \"field\": \"created_at\",\n        \"direction\": \"desc\"\n    },\n    \"sort_order\": 0,\n    \"is_shared\": false,\n    \"is_default\": false\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/smart-lists';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'name' => 'Hot leads, last 7 days',\n            'filters' => [\n                ['field' => 'contact_type', 'operator' => 'eq', 'value' => 'lead'],\n            ],\n            'sort' => ['field' => 'created_at', 'direction' => 'desc'],\n            'sort_order' => 0,\n            'is_shared' => false,\n            'is_default' => false,\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/smart-lists'\npayload = {\n    \"name\": \"Hot leads, last 7 days\",\n    \"filters\": [\n        {\n            \"field\": \"contact_type\",\n            \"operator\": \"eq\",\n            \"value\": \"lead\"\n        }\n    ],\n    \"sort\": {\n        \"field\": \"created_at\",\n        \"direction\": \"desc\"\n    },\n    \"sort_order\": 0,\n    \"is_shared\": false,\n    \"is_default\": false\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  '/api/smart-lists/{id}':
    get:
      summary: 'Fetch a smart list'
      operationId: fetchASmartList
      description: "Its filters and sort, not the contacts it matches — to get those, send the\nsame filters to `GET /api/contacts`. A list you cannot see (somebody\nelse's, unshared) answers `404`."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      location_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      user_id:
                        type: integer
                        examples:
                          - 3768
                      name:
                        type: string
                        examples:
                          - 'aut adipisci'
                      filters:
                        type: array
                        items:
                          type: object
                          properties:
                            field:
                              type: string
                              examples:
                                - contact_type
                            operator:
                              type: string
                              examples:
                                - '='
                            value:
                              type: string
                              examples:
                                - lead
                        examples:
                          -
                            -
                              field: contact_type
                              operator: '='
                              value: lead
                      sort:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      sort_order:
                        type: integer
                        examples:
                          - 2
                      is_shared:
                        type: boolean
                        examples:
                          - false
                      is_default:
                        type: boolean
                        examples:
                          - false
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        404:
          description: 'Does not exist, or belongs to another location'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No query results for model.'
                examples:
                  -
                    message: 'No query results for model.'
      tags:
        - 'Smart Lists'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/smart-lists/5\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/smart-lists/5\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/smart-lists/5';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/smart-lists/5'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    put:
      summary: 'Update a smart list'
      operationId: updateASmartList
      description: "Changes the rule, so it changes who the list finds from the next time\nanybody opens it — 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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      location_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      user_id:
                        type: integer
                        examples:
                          - 3769
                      name:
                        type: string
                        examples:
                          - 'architecto eius'
                      filters:
                        type: array
                        items:
                          type: object
                          properties:
                            field:
                              type: string
                              examples:
                                - contact_type
                            operator:
                              type: string
                              examples:
                                - '='
                            value:
                              type: string
                              examples:
                                - lead
                        examples:
                          -
                            -
                              field: contact_type
                              operator: '='
                              value: lead
                      sort:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      sort_order:
                        type: integer
                        examples:
                          - 0
                      is_shared:
                        type: boolean
                        examples:
                          - false
                      is_default:
                        type: boolean
                        examples:
                          - false
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
      tags:
        - 'Smart Lists'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Display name (max 255).'
                  examples:
                    - 'Hot leads, last 14 days'
                filters:
                  type: array
                  description: 'Filter clauses; same shape as the create payload. Replaces the existing set.'
                  items:
                    type: object
                    properties:
                      field:
                        type: string
                        description: 'This field is required when <code>filters</code> is present.'
                        examples:
                          - architecto
                      operator:
                        type: string
                        description: 'This field is required when <code>filters</code> is present.'
                        examples:
                          - architecto
                      value:
                        type: string
                        description: 'This field is required when <code>filters</code> is present.'
                        examples:
                          - null
                  examples:
                    -
                      - []
                sort:
                  type:
                    - object
                    - 'null'
                  description: 'Default sort `{field, direction}`.'
                  properties:
                    field:
                      type: string
                      description: 'This field is required when <code>sort</code> is present.'
                      examples:
                        - architecto
                    direction:
                      type: string
                      description: 'This field is required when <code>sort</code> is present.'
                      enum:
                        - asc
                        - desc
                      examples:
                        - desc
                  examples:
                    - []
                sort_order:
                  type:
                    - integer
                    - 'null'
                  description: 'Display order.'
                  examples:
                    - 2
                is_shared:
                  type: boolean
                  description: 'Whether the whole team sees the list. Turning it off hides it from everybody but you.'
                  examples:
                    - true
                is_default:
                  type: boolean
                  description: 'Make it the list you land on. Setting it clears the flag on whichever list had it.'
                  examples:
                    - false
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request PUT \\\n    \"https://klozzo.com/api/smart-lists/5\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"name\\\": \\\"Hot leads, last 14 days\\\",\n    \\\"filters\\\": [\n        {\n            \\\"field\\\": \\\"architecto\\\",\n            \\\"operator\\\": \\\"architecto\\\"\n        }\n    ],\n    \\\"sort\\\": {\n        \\\"field\\\": \\\"architecto\\\",\n        \\\"direction\\\": \\\"desc\\\"\n    },\n    \\\"sort_order\\\": 2,\n    \\\"is_shared\\\": true,\n    \\\"is_default\\\": false\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/smart-lists/5\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"name\": \"Hot leads, last 14 days\",\n    \"filters\": [\n        {\n            \"field\": \"architecto\",\n            \"operator\": \"architecto\"\n        }\n    ],\n    \"sort\": {\n        \"field\": \"architecto\",\n        \"direction\": \"desc\"\n    },\n    \"sort_order\": 2,\n    \"is_shared\": true,\n    \"is_default\": false\n};\n\nfetch(url, {\n    method: \"PUT\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/smart-lists/5';\n$response = $client->put(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'name' => 'Hot leads, last 14 days',\n            'filters' => [\n                ['field' => 'architecto', 'operator' => 'architecto'],\n            ],\n            'sort' => ['field' => 'architecto', 'direction' => 'desc'],\n            'sort_order' => 2,\n            'is_shared' => true,\n            'is_default' => false,\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/smart-lists/5'\npayload = {\n    \"name\": \"Hot leads, last 14 days\",\n    \"filters\": [\n        {\n            \"field\": \"architecto\",\n            \"operator\": \"architecto\"\n        }\n    ],\n    \"sort\": {\n        \"field\": \"architecto\",\n        \"direction\": \"desc\"\n    },\n    \"sort_order\": 2,\n    \"is_shared\": true,\n    \"is_default\": false\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('PUT', url, headers=headers, json=payload)\nresponse.json()"
    delete:
      summary: 'Delete a smart list'
      operationId: deleteASmartList
      description: "Deletes a smart list by id, and only the list. **No contact is deleted** — a\nsmart list never owned\nanybody, it only found them — so this is always safe, and it is the one\ndestructive-looking call in this API that is not."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Smart list deleted.'
                examples:
                  -
                    message: 'Smart list deleted.'
      tags:
        - 'Smart Lists'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request DELETE \\\n    \"https://klozzo.com/api/smart-lists/5\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/smart-lists/5\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"DELETE\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/smart-lists/5';\n$response = $client->delete(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/smart-lists/5'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('DELETE', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: id
        description: 'Smart list ID.'
        required: true
        schema:
          type: integer
          examples:
            - 5
  '/api/contacts/{contact_id}/conversations':
    get:
      summary: 'List conversations for a contact'
      operationId: listConversationsForAContact
      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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          examples:
                            - 17
                        contact_id:
                          type: integer
                          examples:
                            - 42
                        location_id:
                          type: integer
                          examples:
                            - 1
                        last_message_at:
                          type: string
                          examples:
                            - '2026-06-05T13:42:00+00:00'
                        last_channel:
                          type: string
                          examples:
                            - whatsapp
                        unread_count:
                          type: integer
                          examples:
                            - 3
                    examples:
                      -
                        -
                          id: 17
                          contact_id: 42
                          location_id: 1
                          last_message_at: '2026-06-05T13:42:00+00:00'
                          last_channel: whatsapp
                          unread_count: 3
                examples:
                  -
                    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
      tags:
        - Conversations
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/contacts/42/conversations\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/42/conversations\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/42/conversations';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/42/conversations'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    post:
      summary: 'Open or fetch a conversation for a contact'
      operationId: openOrFetchAConversationForAContact
      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)."
      parameters: []
      responses:
        200:
          description: 'already existed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        examples:
                          - 17
                      contact_id:
                        type: integer
                        examples:
                          - 42
                      location_id:
                        type: integer
                        examples:
                          - 1
                      last_message_at:
                        type: string
                        examples:
                          - '2026-06-05T13:42:00+00:00'
                      last_channel:
                        type: string
                        examples:
                          - whatsapp
                      unread_count:
                        type: integer
                        examples:
                          - 3
                examples:
                  -
                    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
        201:
          description: 'newly created'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        examples:
                          - 17
                      contact_id:
                        type: integer
                        examples:
                          - 42
                      location_id:
                        type: integer
                        examples:
                          - 1
                      last_message_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      last_channel:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      unread_count:
                        type: integer
                        examples:
                          - 0
                examples:
                  -
                    data:
                      id: 17
                      contact_id: 42
                      location_id: 1
                      last_message_at: null
                      last_channel: null
                      unread_count: 0
      tags:
        - Conversations
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/contacts/42/conversations\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/contacts/42/conversations\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/contacts/42/conversations';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/contacts/42/conversations'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: contact_id
        description: 'Contact ID.'
        required: true
        schema:
          type: integer
          examples:
            - 42
  '/api/conversations/{id}':
    get:
      summary: 'Fetch a conversation'
      operationId: fetchAConversation
      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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        examples:
                          - 17
                      contact_id:
                        type: integer
                        examples:
                          - 42
                      location_id:
                        type: integer
                        examples:
                          - 1
                      last_message_at:
                        type: string
                        examples:
                          - '2026-06-05T13:42:00+00:00'
                      last_channel:
                        type: string
                        examples:
                          - whatsapp
                      unread_count:
                        type: integer
                        examples:
                          - 3
                examples:
                  -
                    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
        403:
          description: 'The contact behind it is not visible to you'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'This action is unauthorized.'
                examples:
                  -
                    message: 'This action is unauthorized.'
        404:
          description: 'Does not exist, or belongs to another location'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No query results for model.'
                examples:
                  -
                    message: 'No query results for model.'
      tags:
        - Conversations
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/conversations/17\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/conversations/17\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/conversations/17';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/conversations/17'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: id
        description: 'Conversation ID.'
        required: true
        schema:
          type: integer
          examples:
            - 17
  '/api/conversations/{conversation_id}/messages':
    get:
      summary: 'List messages in a conversation'
      operationId: listMessagesInAConversation
      description: "Lists the messages of one conversation, oldest first, cursor-paginated by\n`id`. For infinite scroll,\npage backwards using `prev_cursor`."
      parameters:
        -
          in: query
          name: per_page
          description: 'Rows per page. Default 50, maximum 200. See [Lists, paging and filters](#lists-paging-and-filters).'
          required: false
          schema:
            type: integer
            description: 'Rows per page. Default 50, maximum 200. See [Lists, paging and filters](#lists-paging-and-filters).'
            examples:
              - 50
        -
          in: query
          name: cursor
          description: 'Opaque cursor from a previous response.'
          required: false
          schema:
            type: string
            description: 'Opaque cursor from a previous response.'
            examples:
              - architecto
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          examples:
                            - 9001
                        conversation_id:
                          type: integer
                          examples:
                            - 17
                        channel:
                          type: string
                          examples:
                            - whatsapp
                        direction:
                          type: string
                          examples:
                            - outbound
                        body:
                          type: string
                          examples:
                            - 'Hi Ada, your appointment is confirmed.'
                        attachments:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        status:
                          type: string
                          examples:
                            - delivered
                        provider_message_id:
                          type: string
                          examples:
                            - wamid.HBgN...
                        sent_at:
                          type: string
                          examples:
                            - '2026-06-05T13:42:00+00:00'
                        delivered_at:
                          type: string
                          examples:
                            - '2026-06-05T13:42:02+00:00'
                        read_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        error:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        user_id:
                          type: integer
                          examples:
                            - 7
                        created_at:
                          type: string
                          examples:
                            - '2026-06-05T13:42:00+00:00'
                    examples:
                      -
                        -
                          id: 9001
                          conversation_id: 17
                          channel: whatsapp
                          direction: outbound
                          body: 'Hi Ada, your appointment is confirmed.'
                          attachments: null
                          status: delivered
                          provider_message_id: wamid.HBgN...
                          sent_at: '2026-06-05T13:42:00+00:00'
                          delivered_at: '2026-06-05T13:42:02+00:00'
                          read_at: null
                          error: null
                          user_id: 7
                          created_at: '2026-06-05T13:42:00+00:00'
                  next_cursor:
                    type: string
                    examples:
                      - eyJpZCI6OTAwMSwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ
                  prev_cursor:
                    type:
                      - string
                      - 'null'
                    examples:
                      - null
                examples:
                  -
                    data:
                      -
                        id: 9001
                        conversation_id: 17
                        channel: whatsapp
                        direction: outbound
                        body: 'Hi Ada, your appointment is confirmed.'
                        attachments: null
                        status: delivered
                        provider_message_id: wamid.HBgN...
                        sent_at: '2026-06-05T13:42:00+00:00'
                        delivered_at: '2026-06-05T13:42:02+00:00'
                        read_at: null
                        error: null
                        user_id: 7
                        created_at: '2026-06-05T13:42:00+00:00'
                    next_cursor: eyJpZCI6OTAwMSwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ
                    prev_cursor: null
        404:
          description: 'Does not exist, or belongs to another location'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No query results for model.'
                examples:
                  -
                    message: 'No query results for model.'
      tags:
        - Messages
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/conversations/17/messages?per_page=50&cursor=architecto\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/conversations/17/messages\"\n);\n\nconst params = {\n    \"per_page\": \"50\",\n    \"cursor\": \"architecto\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/conversations/17/messages';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'per_page' => '50',\n            'cursor' => 'architecto',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/conversations/17/messages'\nparams = {\n  'per_page': '50',\n  'cursor': 'architecto',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers, params=params)\nresponse.json()"
    post:
      summary: 'Send a message'
      operationId: sendAMessage
      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` → `contact.email`\n- everything else → `contact.phone_e164` or `contact.phone`"
      parameters: []
      responses:
        201:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        examples:
                          - 9001
                      conversation_id:
                        type: integer
                        examples:
                          - 17
                      channel:
                        type: string
                        examples:
                          - whatsapp
                      direction:
                        type: string
                        examples:
                          - outbound
                      body:
                        type: string
                        examples:
                          - 'Hi Ada, your appointment is confirmed.'
                      attachments:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      status:
                        type: string
                        examples:
                          - queued
                      provider_message_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      sent_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      delivered_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      read_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      error:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      user_id:
                        type: integer
                        examples:
                          - 7
                      created_at:
                        type: string
                        examples:
                          - '2026-06-05T13:42:00+00:00'
                examples:
                  -
                    data:
                      id: 9001
                      conversation_id: 17
                      channel: whatsapp
                      direction: outbound
                      body: 'Hi Ada, your appointment is confirmed.'
                      attachments: null
                      status: queued
                      provider_message_id: null
                      sent_at: null
                      delivered_at: null
                      read_at: null
                      error: null
                      user_id: 7
                      created_at: '2026-06-05T13:42:00+00:00'
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'A channel that does not exist'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Channel no es una opción válida.'
                      errors:
                        type: object
                        properties:
                          channel:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Channel no es una opción válida.'
                    examples:
                      -
                        message: 'Channel no es una opción válida.'
                        errors:
                          channel:
                            - 'Channel no es una opción válida.'
                  -
                    description: 'Nothing to send'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Falta body.'
                      errors:
                        type: object
                        properties:
                          body:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Falta body.'
                    examples:
                      -
                        message: 'Falta body.'
                        errors:
                          body:
                            - 'Falta body.'
                  -
                    description: 'The person asked not to be reached on this channel'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'El contacto tiene activado No molestar para este canal.'
                      errors:
                        type: object
                        properties:
                          channel:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'El contacto tiene activado No molestar para este canal.'
                    examples:
                      -
                        message: 'El contacto tiene activado No molestar para este canal.'
                        errors:
                          channel:
                            - 'El contacto tiene activado No molestar para este canal.'
      tags:
        - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                channel:
                  type: string
                  description: 'Channel to send on. One of `sms`, `email`, `whatsapp`, `messenger`, `instagram`, `gmb`.'
                  examples:
                    - whatsapp
                body:
                  type: string
                  description: 'Message body (plain text). Max 8000 chars.'
                  examples:
                    - 'Hi Ada, your appointment is confirmed.'
                attachments:
                  type: array
                  description: 'Optional list of attachment URLs. Provider-specific support.'
                  items:
                    type: string
                  examples:
                    -
                      - architecto
                recipient:
                  type:
                    - string
                    - 'null'
                  description: "Override destination (e.g. specific email or phone). Defaults to the contact's primary handle for the channel."
                  examples:
                    - architecto
              required:
                - channel
                - body
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/conversations/17/messages\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"channel\\\": \\\"whatsapp\\\",\n    \\\"body\\\": \\\"Hi Ada, your appointment is confirmed.\\\",\n    \\\"attachments\\\": [\n        \\\"architecto\\\"\n    ],\n    \\\"recipient\\\": \\\"architecto\\\"\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/conversations/17/messages\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"channel\": \"whatsapp\",\n    \"body\": \"Hi Ada, your appointment is confirmed.\",\n    \"attachments\": [\n        \"architecto\"\n    ],\n    \"recipient\": \"architecto\"\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/conversations/17/messages';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'channel' => 'whatsapp',\n            'body' => 'Hi Ada, your appointment is confirmed.',\n            'attachments' => ['architecto'],\n            'recipient' => 'architecto',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/conversations/17/messages'\npayload = {\n    \"channel\": \"whatsapp\",\n    \"body\": \"Hi Ada, your appointment is confirmed.\",\n    \"attachments\": [\n        \"architecto\"\n    ],\n    \"recipient\": \"architecto\"\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
    parameters:
      -
        in: path
        name: conversation_id
        description: 'Conversation ID.'
        required: true
        schema:
          type: integer
          examples:
            - 17
  /api/message-templates:
    get:
      summary: 'List message templates'
      operationId: listMessageTemplates
      description: "Lists the message templates of this location, newest first. Filter by\nchannel, location, or category."
      parameters:
        -
          in: query
          name: channel
          description: 'Filter by channel. One of `sms`, `email`, `whatsapp`, etc.'
          required: false
          schema:
            type: string
            description: 'Filter by channel. One of `sms`, `email`, `whatsapp`, etc.'
            examples:
              - whatsapp
        -
          in: query
          name: location_id
          description: 'Scope to a location.'
          required: false
          schema:
            type: integer
            description: 'Scope to a location.'
            examples:
              - 1
        -
          in: query
          name: category
          description: 'Optional grouping label.'
          required: false
          schema:
            type: string
            description: 'Optional grouping label.'
            examples:
              - appointment-reminders
        -
          in: query
          name: per_page
          description: 'Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
          required: false
          schema:
            type: integer
            description: 'Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
            examples:
              - 20
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        location_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        user_id:
                          type: integer
                          examples:
                            - 3787
                        name:
                          type: string
                          examples:
                            - 'Template aut adipisci quidem'
                        channel:
                          type: string
                          examples:
                            - sms
                        body:
                          type: string
                          examples:
                            - 'Hi {{contact.first_name}}, thanks for reaching out!'
                        variables:
                          type: array
                          items:
                            type: string
                          examples:
                            -
                              - contact.first_name
                        category:
                          type: string
                          examples:
                            - general
                        created_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        updated_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                    examples:
                      -
                        -
                          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:
                    type: object
                    properties:
                      first:
                        type: string
                        examples:
                          - '/?page=1'
                      last:
                        type: string
                        examples:
                          - '/?page=1'
                      prev:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      next:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        examples:
                          - 1
                      from:
                        type: integer
                        examples:
                          - 1
                      last_page:
                        type: integer
                        examples:
                          - 1
                      links:
                        type: array
                        items:
                          type: object
                          properties:
                            url:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            label:
                              type: string
                              examples:
                                - '&laquo; Previous'
                            page:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            active:
                              type: boolean
                              examples:
                                - false
                        examples:
                          -
                            -
                              url: null
                              label: '&laquo; Previous'
                              page: null
                              active: false
                            -
                              url: '/?page=1'
                              label: '1'
                              page: 1
                              active: true
                            -
                              url: null
                              label: 'Next &raquo;'
                              page: null
                              active: false
                      path:
                        type: string
                        examples:
                          - /
                      per_page:
                        type: integer
                        examples:
                          - 20
                      to:
                        type: integer
                        examples:
                          - 2
                      total:
                        type: integer
                        examples:
                          - 2
                examples:
                  -
                    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: '&laquo; Previous'
                          page: null
                          active: false
                        -
                          url: '/?page=1'
                          label: '1'
                          page: 1
                          active: true
                        -
                          url: null
                          label: 'Next &raquo;'
                          page: null
                          active: false
                      path: /
                      per_page: 20
                      to: 2
                      total: 2
      tags:
        - 'Message Templates'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/message-templates?channel=whatsapp&location_id=1&category=appointment-reminders&per_page=20\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/message-templates\"\n);\n\nconst params = {\n    \"channel\": \"whatsapp\",\n    \"location_id\": \"1\",\n    \"category\": \"appointment-reminders\",\n    \"per_page\": \"20\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/message-templates';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'channel' => 'whatsapp',\n            'location_id' => '1',\n            'category' => 'appointment-reminders',\n            'per_page' => '20',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/message-templates'\nparams = {\n  'channel': 'whatsapp',\n  'location_id': '1',\n  'category': 'appointment-reminders',\n  'per_page': '20',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers, params=params)\nresponse.json()"
    post:
      summary: 'Create a message template'
      operationId: createAMessageTemplate
      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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      location_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      user_id:
                        type: integer
                        examples:
                          - 3789
                      name:
                        type: string
                        examples:
                          - 'Template et animi quos'
                      channel:
                        type: string
                        examples:
                          - sms
                      body:
                        type: string
                        examples:
                          - 'Hi {{contact.first_name}}, thanks for reaching out!'
                      variables:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - contact.first_name
                      category:
                        type: string
                        examples:
                          - general
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'A channel that does not exist'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Channel no es una opción válida.'
                      errors:
                        type: object
                        properties:
                          channel:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Channel no es una opción válida.'
                    examples:
                      -
                        message: 'Channel no es una opción válida.'
                        errors:
                          channel:
                            - 'Channel no es una opción válida.'
                  -
                    description: 'An empty body'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Falta body.'
                      errors:
                        type: object
                        properties:
                          body:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Falta body.'
                    examples:
                      -
                        message: 'Falta body.'
                        errors:
                          body:
                            - 'Falta body.'
      tags:
        - 'Message Templates'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                location_id:
                  type:
                    - integer
                    - 'null'
                  description: 'Scope to a specific location.'
                  examples:
                    - 1
                name:
                  type: string
                  description: 'Display name (max 120).'
                  examples:
                    - 'Appointment reminder'
                channel:
                  type: string
                  description: 'One of `sms`, `email`, `whatsapp`, `messenger`, `instagram`, `gmb`.'
                  examples:
                    - whatsapp
                body:
                  type: string
                  description: 'Template body with `@{{variable}}` placeholders.'
                  examples:
                    - 'Hi @{{first_name}}, your appointment is on @{{appointment_date}}.'
                category:
                  type:
                    - string
                    - 'null'
                  description: 'Optional grouping label (max 60).'
                  examples:
                    - appointment-reminders
              required:
                - name
                - channel
                - body
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/message-templates\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"location_id\\\": 1,\n    \\\"name\\\": \\\"Appointment reminder\\\",\n    \\\"channel\\\": \\\"whatsapp\\\",\n    \\\"body\\\": \\\"Hi @{{first_name}}, your appointment is on @{{appointment_date}}.\\\",\n    \\\"category\\\": \\\"appointment-reminders\\\"\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/message-templates\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"location_id\": 1,\n    \"name\": \"Appointment reminder\",\n    \"channel\": \"whatsapp\",\n    \"body\": \"Hi @{{first_name}}, your appointment is on @{{appointment_date}}.\",\n    \"category\": \"appointment-reminders\"\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/message-templates';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'location_id' => 1,\n            'name' => 'Appointment reminder',\n            'channel' => 'whatsapp',\n            'body' => 'Hi @{{first_name}}, your appointment is on @{{appointment_date}}.',\n            'category' => 'appointment-reminders',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/message-templates'\npayload = {\n    \"location_id\": 1,\n    \"name\": \"Appointment reminder\",\n    \"channel\": \"whatsapp\",\n    \"body\": \"Hi @{{first_name}}, your appointment is on @{{appointment_date}}.\",\n    \"category\": \"appointment-reminders\"\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  '/api/message-templates/{messageTemplate_id}':
    get:
      summary: 'Fetch a message template'
      operationId: fetchAMessageTemplate
      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 — the CRM knows about custom fields and fallbacks, and your string\nreplace does not."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      location_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      user_id:
                        type: integer
                        examples:
                          - 3790
                      name:
                        type: string
                        examples:
                          - 'Template nostrum qui commodi'
                      channel:
                        type: string
                        examples:
                          - sms
                      body:
                        type: string
                        examples:
                          - 'Hi {{contact.first_name}}, thanks for reaching out!'
                      variables:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - contact.first_name
                      category:
                        type: string
                        examples:
                          - general
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        404:
          description: 'Does not exist, or belongs to another location'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No query results for model.'
                examples:
                  -
                    message: 'No query results for model.'
      tags:
        - 'Message Templates'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/message-templates/11\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/message-templates/11\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/message-templates/11';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/message-templates/11'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    delete:
      summary: 'Delete a message template'
      operationId: deleteAMessageTemplate
      description: "Deletes a message template by id, so it stops being offered when composing.\nMessages already sent from it are\nuntouched — they\nwere rendered to plain text at send time and do not reference it."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Template deleted.'
                examples:
                  -
                    message: 'Template deleted.'
      tags:
        - 'Message Templates'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request DELETE \\\n    \"https://klozzo.com/api/message-templates/11\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/message-templates/11\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"DELETE\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/message-templates/11';\n$response = $client->delete(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/message-templates/11'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('DELETE', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: messageTemplate_id
        description: 'Template ID.'
        required: true
        schema:
          type: integer
          examples:
            - 11
  '/api/message-templates/{messageTemplate_id}/render':
    post:
      summary: 'Render template against a contact'
      operationId: renderTemplateAgainstAContact
      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)."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: ''
                    type: object
                    properties:
                      rendered:
                        type: string
                        examples:
                          - 'Hi Ada, your appointment is on 2026-06-08.'
                      missing:
                        type: array
                        examples:
                          - []
                      channel:
                        type: string
                        examples:
                          - whatsapp
                    examples:
                      -
                        rendered: 'Hi Ada, your appointment is on 2026-06-08.'
                        missing: []
                        channel: whatsapp
                  -
                    description: 'unresolved variables'
                    type: object
                    properties:
                      rendered:
                        type: string
                        examples:
                          - 'Hi Ada, your appointment is on @{{appointment_date}}.'
                      missing:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - appointment_date
                      channel:
                        type: string
                        examples:
                          - whatsapp
                    examples:
                      -
                        rendered: 'Hi Ada, your appointment is on @{{appointment_date}}.'
                        missing:
                          - appointment_date
                        channel: whatsapp
      tags:
        - 'Message Templates'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contact_id:
                  type: integer
                  description: 'Contact to render against.'
                  examples:
                    - 42
              required:
                - contact_id
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/message-templates/11/render\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"contact_id\\\": 42\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/message-templates/11/render\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"contact_id\": 42\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/message-templates/11/render';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'contact_id' => 42,\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/message-templates/11/render'\npayload = {\n    \"contact_id\": 42\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
    parameters:
      -
        in: path
        name: messageTemplate_id
        description: 'Template ID.'
        required: true
        schema:
          type: integer
          examples:
            - 11
  /api/channel-integrations:
    get:
      summary: 'List channel integrations'
      operationId: listChannelIntegrations
      description: "Lists the channel integrations of this location — WhatsApp, email, SMS —\nnewest first. Filter by location, channel, or status."
      parameters:
        -
          in: query
          name: location_id
          description: 'Scope to a location.'
          required: false
          schema:
            type: integer
            description: 'Scope to a location.'
            examples:
              - 1
        -
          in: query
          name: channel
          description: 'Filter by channel. One of `whatsapp`, `messenger`, `instagram`, `gmb`.'
          required: false
          schema:
            type: string
            description: 'Filter by channel. One of `whatsapp`, `messenger`, `instagram`, `gmb`.'
            examples:
              - whatsapp
        -
          in: query
          name: status
          description: 'Filter by status (e.g. `active`, `disconnected`, `expired`).'
          required: false
          schema:
            type: string
            description: 'Filter by status (e.g. `active`, `disconnected`, `expired`).'
            examples:
              - active
        -
          in: query
          name: per_page
          description: 'Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
          required: false
          schema:
            type: integer
            description: 'Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
            examples:
              - 20
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        location_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        channel:
                          type: string
                          examples:
                            - whatsapp
                        status:
                          type: string
                          examples:
                            - connected
                        metadata:
                          type: object
                          properties:
                            account_id:
                              type: string
                              examples:
                                - acct_g2gh67JMFZ
                        connected_at:
                          type: string
                          examples:
                            - '2026-08-26T02:19:50+00:00'
                        disconnected_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        expires_at:
                          type: string
                          examples:
                            - '2026-08-26T04:19:50+00:00'
                        created_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                    examples:
                      -
                        -
                          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:
                    type: object
                    properties:
                      first:
                        type: string
                        examples:
                          - '/?page=1'
                      last:
                        type: string
                        examples:
                          - '/?page=1'
                      prev:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      next:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        examples:
                          - 1
                      from:
                        type: integer
                        examples:
                          - 1
                      last_page:
                        type: integer
                        examples:
                          - 1
                      links:
                        type: array
                        items:
                          type: object
                          properties:
                            url:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            label:
                              type: string
                              examples:
                                - '&laquo; Previous'
                            page:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            active:
                              type: boolean
                              examples:
                                - false
                        examples:
                          -
                            -
                              url: null
                              label: '&laquo; Previous'
                              page: null
                              active: false
                            -
                              url: '/?page=1'
                              label: '1'
                              page: 1
                              active: true
                            -
                              url: null
                              label: 'Next &raquo;'
                              page: null
                              active: false
                      path:
                        type: string
                        examples:
                          - /
                      per_page:
                        type: integer
                        examples:
                          - 20
                      to:
                        type: integer
                        examples:
                          - 2
                      total:
                        type: integer
                        examples:
                          - 2
                examples:
                  -
                    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: '&laquo; Previous'
                          page: null
                          active: false
                        -
                          url: '/?page=1'
                          label: '1'
                          page: 1
                          active: true
                        -
                          url: null
                          label: 'Next &raquo;'
                          page: null
                          active: false
                      path: /
                      per_page: 20
                      to: 2
                      total: 2
      tags:
        - 'Channel Integrations'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/channel-integrations?location_id=1&channel=whatsapp&status=active&per_page=20\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/channel-integrations\"\n);\n\nconst params = {\n    \"location_id\": \"1\",\n    \"channel\": \"whatsapp\",\n    \"status\": \"active\",\n    \"per_page\": \"20\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/channel-integrations';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'location_id' => '1',\n            'channel' => 'whatsapp',\n            'status' => 'active',\n            'per_page' => '20',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/channel-integrations'\nparams = {\n  'location_id': '1',\n  'channel': 'whatsapp',\n  'status': 'active',\n  'per_page': '20',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers, params=params)\nresponse.json()"
    post:
      summary: 'Connect a channel integration'
      operationId: connectAChannelIntegration
      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)."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      location_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      channel:
                        type: string
                        examples:
                          - whatsapp
                      status:
                        type: string
                        examples:
                          - connected
                      metadata:
                        type: object
                        properties:
                          account_id:
                            type: string
                            examples:
                              - acct_ZmVG5xkxyX
                      connected_at:
                        type: string
                        examples:
                          - '2026-08-26T02:19:50+00:00'
                      disconnected_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      expires_at:
                        type: string
                        examples:
                          - '2026-08-26T04:19:50+00:00'
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'A channel that does not exist'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Channel no es una opción válida.'
                      errors:
                        type: object
                        properties:
                          channel:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Channel no es una opción válida.'
                    examples:
                      -
                        message: 'Channel no es una opción válida.'
                        errors:
                          channel:
                            - 'Channel no es una opción válida.'
                  -
                    description: 'No credentials'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Falta credentials.access_token.'
                      errors:
                        type: object
                        properties:
                          credentials.access_token:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Falta credentials.access_token.'
                    examples:
                      -
                        message: 'Falta credentials.access_token.'
                        errors:
                          credentials.access_token:
                            - 'Falta credentials.access_token.'
                  -
                    description: 'A location you do not belong to'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Location id no es válido.'
                      errors:
                        type: object
                        properties:
                          location_id:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Location id no es válido.'
                    examples:
                      -
                        message: 'Location id no es válido.'
                        errors:
                          location_id:
                            - 'Location id no es válido.'
      tags:
        - 'Channel Integrations'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                channel:
                  type: string
                  description: 'One of `whatsapp`, `messenger`, `instagram`, `gmb`.'
                  examples:
                    - whatsapp
                location_id:
                  type: integer
                  description: 'A location you are a member of. Defaults to your current location.'
                  examples:
                    - 1
                credentials:
                  type: object
                  description: 'Provider credentials. Must include `access_token`.'
                  properties:
                    access_token:
                      type: string
                      description: 'Long-lived access token.'
                      examples:
                        - architecto
                    refresh_token:
                      type:
                        - string
                        - 'null'
                      description: 'Optional refresh token.'
                      examples:
                        - architecto
                  required:
                    - access_token
                  examples:
                    - []
                metadata:
                  type:
                    - object
                    - 'null'
                  description: 'Provider-specific metadata (e.g. `{ "phone_number_id": "..." }` for WhatsApp).'
                  properties: {  }
                  examples:
                    - []
                expires_in:
                  type:
                    - integer
                    - 'null'
                  description: 'Seconds until access token expires. Used to compute `expires_at`.'
                  examples:
                    - 3600
              required:
                - channel
                - credentials
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/channel-integrations\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"channel\\\": \\\"whatsapp\\\",\n    \\\"location_id\\\": 1,\n    \\\"credentials\\\": {\n        \\\"access_token\\\": \\\"architecto\\\",\n        \\\"refresh_token\\\": \\\"architecto\\\"\n    },\n    \\\"metadata\\\": [],\n    \\\"expires_in\\\": 3600\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/channel-integrations\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"channel\": \"whatsapp\",\n    \"location_id\": 1,\n    \"credentials\": {\n        \"access_token\": \"architecto\",\n        \"refresh_token\": \"architecto\"\n    },\n    \"metadata\": [],\n    \"expires_in\": 3600\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/channel-integrations';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'channel' => 'whatsapp',\n            'location_id' => 1,\n            'credentials' => ['access_token' => 'architecto', 'refresh_token' => 'architecto'],\n            'metadata' => [],\n            'expires_in' => 3600,\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/channel-integrations'\npayload = {\n    \"channel\": \"whatsapp\",\n    \"location_id\": 1,\n    \"credentials\": {\n        \"access_token\": \"architecto\",\n        \"refresh_token\": \"architecto\"\n    },\n    \"metadata\": [],\n    \"expires_in\": 3600\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  '/api/channel-integrations/{channelIntegration_id}':
    get:
      summary: 'Fetch a channel integration'
      operationId: fetchAChannelIntegration
      description: "Returns one channel integration by id. Credentials come back in\nencrypted/redacted form; only metadata and\nstatus are usable client-side."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      location_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      channel:
                        type: string
                        examples:
                          - whatsapp
                      status:
                        type: string
                        examples:
                          - connected
                      metadata:
                        type: object
                        properties:
                          account_id:
                            type: string
                            examples:
                              - acct_yB1hXM3BMo
                      connected_at:
                        type: string
                        examples:
                          - '2026-08-26T02:19:50+00:00'
                      disconnected_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      expires_at:
                        type: string
                        examples:
                          - '2026-08-26T04:19:50+00:00'
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        404:
          description: 'Does not exist, or belongs to another location'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No query results for model.'
                examples:
                  -
                    message: 'No query results for model.'
      tags:
        - 'Channel Integrations'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/channel-integrations/4\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/channel-integrations/4\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/channel-integrations/4';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/channel-integrations/4'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    delete:
      summary: 'Disconnect a channel integration'
      operationId: disconnectAChannelIntegration
      description: "Marks the integration `disconnected` and clears stored credentials. Existing\nconversations remain readable; outbound messages on this channel will fail\nuntil reconnected."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Channel integration disconnected.'
                examples:
                  -
                    message: 'Channel integration disconnected.'
      tags:
        - 'Channel Integrations'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request DELETE \\\n    \"https://klozzo.com/api/channel-integrations/4\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/channel-integrations/4\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"DELETE\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/channel-integrations/4';\n$response = $client->delete(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/channel-integrations/4'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('DELETE', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: channelIntegration_id
        description: 'Integration ID.'
        required: true
        schema:
          type: integer
          examples:
            - 4
  '/api/channel-integrations/{channelIntegration_id}/refresh':
    post:
      summary: 'Refresh integration tokens'
      operationId: refreshIntegrationTokens
      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 —\nthe user must re-OAuth in product)."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      location_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      channel:
                        type: string
                        examples:
                          - whatsapp
                      status:
                        type: string
                        examples:
                          - connected
                      metadata:
                        type: object
                        properties:
                          account_id:
                            type: string
                            examples:
                              - acct_sKkxJlPy6M
                      connected_at:
                        type: string
                        examples:
                          - '2026-08-26T02:19:50+00:00'
                      disconnected_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      expires_at:
                        type: string
                        examples:
                          - '2026-08-26T04:19:50+00:00'
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        502:
          description: 'refresh failed'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Refresh token rejected by provider'
                examples:
                  -
                    message: 'Refresh token rejected by provider'
      tags:
        - 'Channel Integrations'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/channel-integrations/4/refresh\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/channel-integrations/4/refresh\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/channel-integrations/4/refresh';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/channel-integrations/4/refresh'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: channelIntegration_id
        description: 'Integration ID.'
        required: true
        schema:
          type: integer
          examples:
            - 4
  /api/v1/companies:
    get:
      summary: 'List companies'
      operationId: listCompanies
      description: 'Lists the companies of the location the API token belongs to.'
      parameters:
        -
          in: query
          name: search
          description: 'Free text over name, legal name and RFC.'
          required: false
          schema:
            type: string
            description: 'Free text over name, legal name and RFC.'
            examples:
              - ADPA
        -
          in: query
          name: external_ref
          description: 'Find the one carrying your identifier.'
          required: false
          schema:
            type: string
            description: 'Find the one carrying your identifier.'
            examples:
              - verificamex-99
        -
          in: query
          name: per_page
          description: 'Rows per page. Default 50, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
          required: false
          schema:
            type: integer
            description: 'Rows per page. Default 50, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
            examples:
              - 50
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        ulid:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        name:
                          type: string
                          examples:
                            - 'Price Ltd'
                        legal_name:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        tax_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        tax_regime:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        cfdi_use:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        address:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        email:
                          type: string
                          examples:
                            - contacto@cronin.example
                        phone:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        website:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        industry:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        owner_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        external_ref:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        notes:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        created_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        updated_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                    examples:
                      -
                        -
                          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
                examples:
                  -
                    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
      tags:
        - 'Negocios y Cotizaciones'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/v1/companies?search=ADPA&external_ref=verificamex-99&per_page=50\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/companies\"\n);\n\nconst params = {\n    \"search\": \"ADPA\",\n    \"external_ref\": \"verificamex-99\",\n    \"per_page\": \"50\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/companies';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'search' => 'ADPA',\n            'external_ref' => 'verificamex-99',\n            'per_page' => '50',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/companies'\nparams = {\n  'search': 'ADPA',\n  'external_ref': 'verificamex-99',\n  'per_page': '50',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers, params=params)\nresponse.json()"
    post:
      summary: 'Create a company'
      operationId: createACompany
      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 — 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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      ulid:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      name:
                        type: string
                        examples:
                          - 'Price Ltd'
                      legal_name:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      tax_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      tax_regime:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      cfdi_use:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      address:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      email:
                        type: string
                        examples:
                          - contacto@dare.example
                      phone:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      website:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      industry:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      owner_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      external_ref:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      notes:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'No name'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Falta el nombre.'
                      errors:
                        type: object
                        properties:
                          name:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Falta el nombre.'
                    examples:
                      -
                        message: 'Falta el nombre.'
                        errors:
                          name:
                            - 'Falta el nombre.'
                  -
                    description: 'An RFC already registered here'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'El valor de tax id ya está en uso.'
                      errors:
                        type: object
                        properties:
                          tax_id:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'El valor de tax id ya está en uso.'
                    examples:
                      -
                        message: 'El valor de tax id ya está en uso.'
                        errors:
                          tax_id:
                            - 'El valor de tax id ya está en uso.'
                  -
                    description: 'An external_ref already used'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'El valor de external ref ya está en uso.'
                      errors:
                        type: object
                        properties:
                          external_ref:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'El valor de external ref ya está en uso.'
                    examples:
                      -
                        message: 'El valor de external ref ya está en uso.'
                        errors:
                          external_ref:
                            - 'El valor de external ref ya está en uso.'
      tags:
        - 'Negocios y Cotizaciones'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Trading name.'
                  examples:
                    - ADPA
                legal_name:
                  type: string
                  description: 'Razón social.'
                  examples:
                    - 'ADPA, S.A. de C.V.'
                tax_id:
                  type: string
                  description: 'RFC. Unique inside the location.'
                  examples:
                    - ADP010101AB1
                tax_regime:
                  type: string
                  description: 'SAT regime code.'
                  examples:
                    - '601'
                cfdi_use:
                  type: string
                  description: 'SAT CFDI use code.'
                  examples:
                    - G03
                email:
                  type: string
                  description: ''
                  examples:
                    - contacto@example.com
                phone:
                  type: string
                  description: "The company switchboard. Free text: unlike a contact's phone this one is neither validated nor normalised, so send E.164 if you intend to dial it."
                  examples:
                    - '+525555555555'
                external_ref:
                  type: string
                  description: 'Your identifier for this company. Unique inside the location.'
                  examples:
                    - verificamex-99
              required:
                - name
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/v1/companies\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"name\\\": \\\"ADPA\\\",\n    \\\"legal_name\\\": \\\"ADPA, S.A. de C.V.\\\",\n    \\\"tax_id\\\": \\\"ADP010101AB1\\\",\n    \\\"tax_regime\\\": \\\"601\\\",\n    \\\"cfdi_use\\\": \\\"G03\\\",\n    \\\"email\\\": \\\"contacto@example.com\\\",\n    \\\"phone\\\": \\\"+525555555555\\\",\n    \\\"external_ref\\\": \\\"verificamex-99\\\"\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/companies\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"name\": \"ADPA\",\n    \"legal_name\": \"ADPA, S.A. de C.V.\",\n    \"tax_id\": \"ADP010101AB1\",\n    \"tax_regime\": \"601\",\n    \"cfdi_use\": \"G03\",\n    \"email\": \"contacto@example.com\",\n    \"phone\": \"+525555555555\",\n    \"external_ref\": \"verificamex-99\"\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/companies';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'name' => 'ADPA',\n            'legal_name' => 'ADPA, S.A. de C.V.',\n            'tax_id' => 'ADP010101AB1',\n            'tax_regime' => '601',\n            'cfdi_use' => 'G03',\n            'email' => 'contacto@example.com',\n            'phone' => '+525555555555',\n            'external_ref' => 'verificamex-99',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/companies'\npayload = {\n    \"name\": \"ADPA\",\n    \"legal_name\": \"ADPA, S.A. de C.V.\",\n    \"tax_id\": \"ADP010101AB1\",\n    \"tax_regime\": \"601\",\n    \"cfdi_use\": \"G03\",\n    \"email\": \"contacto@example.com\",\n    \"phone\": \"+525555555555\",\n    \"external_ref\": \"verificamex-99\"\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  '/api/v1/companies/{ulid}':
    get:
      summary: 'Fetch a company'
      operationId: fetchACompany
      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` — telling an\noutsider \"that exists but is not yours\" is telling them it exists."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      ulid:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      name:
                        type: string
                        examples:
                          - 'Price Ltd'
                      legal_name:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      tax_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      tax_regime:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      cfdi_use:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      address:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      email:
                        type: string
                        examples:
                          - contacto@hauck.example
                      phone:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      website:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      industry:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      owner_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      external_ref:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      notes:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
      tags:
        - 'Negocios y Cotizaciones'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/v1/companies/01JZ8Z0ZP0000000000000000\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/companies/01JZ8Z0ZP0000000000000000\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/companies/01JZ8Z0ZP0000000000000000';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/companies/01JZ8Z0ZP0000000000000000'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    put:
      summary: 'Update a company'
      operationId: updateACompany
      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 —\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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      ulid:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      name:
                        type: string
                        examples:
                          - 'Price Ltd'
                      legal_name:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      tax_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      tax_regime:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      cfdi_use:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      address:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      email:
                        type: string
                        examples:
                          - contacto@leuschke.example
                      phone:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      website:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      industry:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      owner_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      external_ref:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      notes:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
      tags:
        - 'Negocios y Cotizaciones'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request PUT \\\n    \"https://klozzo.com/api/v1/companies/01JZ8Z0ZP0000000000000000\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/companies/01JZ8Z0ZP0000000000000000\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"PUT\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/companies/01JZ8Z0ZP0000000000000000';\n$response = $client->put(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/companies/01JZ8Z0ZP0000000000000000'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('PUT', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: ulid
        description: 'Company ULID (a numeric id still resolves).'
        required: true
        schema:
          type: string
          examples:
            - 01JZ8Z0ZP0000000000000000
  /api/v1/deals:
    get:
      summary: 'List deals'
      operationId: listDeals
      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 — it is whose token you are using."
      parameters:
        -
          in: query
          name: status
          description: 'One of `open`, `won`, `lost`.'
          required: false
          schema:
            type: string
            description: 'One of `open`, `won`, `lost`.'
            examples:
              - open
        -
          in: query
          name: company_id
          description: "Only this company's deals."
          required: false
          schema:
            type: integer
            description: "Only this company's deals."
            examples:
              - 12
        -
          in: query
          name: external_ref
          description: 'Find the one carrying your identifier.'
          required: false
          schema:
            type: string
            description: 'Find the one carrying your identifier.'
            examples:
              - sub_88213
        -
          in: query
          name: per_page
          description: 'Rows per page. Default 50, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
          required: false
          schema:
            type: integer
            description: 'Rows per page. Default 50, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
            examples:
              - 50
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          examples:
                            - 1
                        ulid:
                          type: string
                          examples:
                            - 01KYDKV7N1RMWVK8H79M9H20V1
                        title:
                          type: string
                          examples:
                            - 'ADPA — Paquete 1,100 firmas'
                        description:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        status:
                          type: string
                          examples:
                            - open
                        status_label:
                          type: string
                          examples:
                            - Abierto
                        amount:
                          type: object
                          properties:
                            amount:
                              type: integer
                              examples:
                                - 250140000
                            currency:
                              type: string
                              examples:
                                - MXN
                            decimal:
                              type: string
                              examples:
                                - '25014.0000'
                            formatted:
                              type: string
                              examples:
                                - '$25,014.00'
                        paid:
                          type: object
                          properties:
                            amount:
                              type: integer
                              examples:
                                - 0
                            currency:
                              type: string
                              examples:
                                - MXN
                            decimal:
                              type: string
                              examples:
                                - '0.0000'
                            formatted:
                              type: string
                              examples:
                                - $0.00
                        balance:
                          type: object
                          properties:
                            amount:
                              type: integer
                              examples:
                                - 250140000
                            currency:
                              type: string
                              examples:
                                - MXN
                            decimal:
                              type: string
                              examples:
                                - '25014.0000'
                            formatted:
                              type: string
                              examples:
                                - '$25,014.00'
                        weighted_amount:
                          type: object
                          properties:
                            amount:
                              type: integer
                              examples:
                                - 100056000
                            currency:
                              type: string
                              examples:
                                - MXN
                            decimal:
                              type: string
                              examples:
                                - '10005.6000'
                            formatted:
                              type: string
                              examples:
                                - '$10,005.60'
                        currency:
                          type: string
                          examples:
                            - MXN
                        pipeline_id:
                          type: integer
                          examples:
                            - 1
                        pipeline_stage_id:
                          type: integer
                          examples:
                            - 2
                        stage:
                          type: object
                          properties:
                            id:
                              type: integer
                              examples:
                                - 2
                            name:
                              type: string
                              examples:
                                - 'Cotización enviada'
                            probability:
                              type: integer
                              examples:
                                - 40
                            is_won:
                              type: boolean
                              examples:
                                - false
                            is_lost:
                              type: boolean
                              examples:
                                - false
                        company_id:
                          type: integer
                          examples:
                            - 1
                        primary_contact_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        owner_id:
                          type: integer
                          examples:
                            - 26
                        expected_close_date:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        closed_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        lost_reason:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        source:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        attribution:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        external_ref:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        created_at:
                          type: string
                          examples:
                            - '2026-07-25T03:58:03+00:00'
                        updated_at:
                          type: string
                          examples:
                            - '2026-07-25T03:58:03+00:00'
                    examples:
                      -
                        -
                          id: 1
                          ulid: 01KYDKV7N1RMWVK8H79M9H20V1
                          title: 'ADPA — 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ón 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 — 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ón 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'
                examples:
                  -
                    data:
                      -
                        id: 1
                        ulid: 01KYDKV7N1RMWVK8H79M9H20V1
                        title: 'ADPA — 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ón 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 — 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ón 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'
      tags:
        - 'Negocios y Cotizaciones'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/v1/deals?status=open&company_id=12&external_ref=sub_88213&per_page=50\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/deals\"\n);\n\nconst params = {\n    \"status\": \"open\",\n    \"company_id\": \"12\",\n    \"external_ref\": \"sub_88213\",\n    \"per_page\": \"50\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/deals';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'status' => 'open',\n            'company_id' => '12',\n            'external_ref' => 'sub_88213',\n            'per_page' => '50',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/deals'\nparams = {\n  'status': 'open',\n  'company_id': '12',\n  'external_ref': 'sub_88213',\n  'per_page': '50',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers, params=params)\nresponse.json()"
    post:
      summary: 'Create a deal'
      operationId: createADeal
      description: "Creates a deal — an opportunity — 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)."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        examples:
                          - 1
                      ulid:
                        type: string
                        examples:
                          - 01KYDKV7N1RMWVK8H79M9H20V1
                      title:
                        type: string
                        examples:
                          - 'ADPA — Paquete 1,100 firmas'
                      description:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      status:
                        type: string
                        examples:
                          - open
                      status_label:
                        type: string
                        examples:
                          - Abierto
                      amount:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 250140000
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '25014.0000'
                          formatted:
                            type: string
                            examples:
                              - '$25,014.00'
                      paid:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 0
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '0.0000'
                          formatted:
                            type: string
                            examples:
                              - $0.00
                      balance:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 250140000
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '25014.0000'
                          formatted:
                            type: string
                            examples:
                              - '$25,014.00'
                      weighted_amount:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 100056000
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '10005.6000'
                          formatted:
                            type: string
                            examples:
                              - '$10,005.60'
                      currency:
                        type: string
                        examples:
                          - MXN
                      pipeline_id:
                        type: integer
                        examples:
                          - 1
                      pipeline_stage_id:
                        type: integer
                        examples:
                          - 2
                      stage:
                        type: object
                        properties:
                          id:
                            type: integer
                            examples:
                              - 2
                          name:
                            type: string
                            examples:
                              - 'Cotización enviada'
                          probability:
                            type: integer
                            examples:
                              - 40
                          is_won:
                            type: boolean
                            examples:
                              - false
                          is_lost:
                            type: boolean
                            examples:
                              - false
                      company_id:
                        type: integer
                        examples:
                          - 1
                      primary_contact_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      owner_id:
                        type: integer
                        examples:
                          - 26
                      expected_close_date:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      closed_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      lost_reason:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      source:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      attribution:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      external_ref:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type: string
                        examples:
                          - '2026-07-25T03:58:03+00:00'
                      updated_at:
                        type: string
                        examples:
                          - '2026-07-25T03:58:03+00:00'
                examples:
                  -
                    data:
                      id: 1
                      ulid: 01KYDKV7N1RMWVK8H79M9H20V1
                      title: 'ADPA — 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ón 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'
      tags:
        - 'Negocios y Cotizaciones'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: 'What is being sold.'
                  examples:
                    - 'ADPA — Paquete 1,100 firmas'
                description:
                  type:
                    - string
                    - 'null'
                  description: 'Must not be greater than 5000 characters.'
                  examples:
                    - 'Et animi quos velit et fugiat.'
                company_id:
                  type:
                    - integer
                    - 'null'
                  description: 'The customer company.'
                  examples:
                    - 12
                primary_contact_id:
                  type:
                    - integer
                    - 'null'
                  description: 'The person on the other end.'
                  examples:
                    - 340
                owner_id:
                  type:
                    - integer
                    - 'null'
                  description: "The agent responsible. Defaults to the token's user."
                  examples:
                    - 4
                pipeline_id:
                  type:
                    - integer
                    - 'null'
                  description: "Defaults to the location's default pipeline."
                  examples:
                    - 1
                pipeline_stage_id:
                  type:
                    - string
                    - 'null'
                  description: ''
                  examples:
                    - null
                expected_close_date:
                  type:
                    - string
                    - 'null'
                  description: ''
                  examples:
                    - '2026-08-30'
                source:
                  type:
                    - string
                    - 'null'
                  description: 'Where it came from.'
                  examples:
                    - verificamex
                external_ref:
                  type:
                    - string
                    - 'null'
                  description: 'Your identifier for this deal. Unique inside the location.'
                  examples:
                    - sub_88213
              required:
                - title
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/v1/deals\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"title\\\": \\\"ADPA — Paquete 1,100 firmas\\\",\n    \\\"description\\\": \\\"Et animi quos velit et fugiat.\\\",\n    \\\"company_id\\\": 12,\n    \\\"primary_contact_id\\\": 340,\n    \\\"owner_id\\\": 4,\n    \\\"pipeline_id\\\": 1,\n    \\\"expected_close_date\\\": \\\"2026-08-30\\\",\n    \\\"source\\\": \\\"verificamex\\\",\n    \\\"external_ref\\\": \\\"sub_88213\\\"\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/deals\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"title\": \"ADPA — Paquete 1,100 firmas\",\n    \"description\": \"Et animi quos velit et fugiat.\",\n    \"company_id\": 12,\n    \"primary_contact_id\": 340,\n    \"owner_id\": 4,\n    \"pipeline_id\": 1,\n    \"expected_close_date\": \"2026-08-30\",\n    \"source\": \"verificamex\",\n    \"external_ref\": \"sub_88213\"\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/deals';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'title' => 'ADPA — Paquete 1,100 firmas',\n            'description' => 'Et animi quos velit et fugiat.',\n            'company_id' => 12,\n            'primary_contact_id' => 340,\n            'owner_id' => 4,\n            'pipeline_id' => 1,\n            'expected_close_date' => '2026-08-30',\n            'source' => 'verificamex',\n            'external_ref' => 'sub_88213',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/deals'\npayload = {\n    \"title\": \"ADPA — Paquete 1,100 firmas\",\n    \"description\": \"Et animi quos velit et fugiat.\",\n    \"company_id\": 12,\n    \"primary_contact_id\": 340,\n    \"owner_id\": 4,\n    \"pipeline_id\": 1,\n    \"expected_close_date\": \"2026-08-30\",\n    \"source\": \"verificamex\",\n    \"external_ref\": \"sub_88213\"\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  /api/v1/deals/reconcile:
    post:
      summary: 'Reconcile a deal'
      operationId: reconcileADeal
      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 — 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."
      parameters:
        -
          in: header
          name: Idempotency-Key
          description: ''
          schema:
            type: string
            examples:
              - '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'
      responses:
        200:
          description: Reconciled
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        examples:
                          - won
                  meta:
                    type: object
                    properties:
                      reconciled:
                        type: boolean
                        examples:
                          - true
                      payment_recorded:
                        type: boolean
                        examples:
                          - true
                examples:
                  -
                    data:
                      status: won
                    meta:
                      reconciled: true
                      payment_recorded: true
        404:
          description: 'Nothing to reconcile'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No hay ningún negocio con ese external_ref.'
                examples:
                  -
                    message: 'No hay ningún negocio con ese external_ref.'
        409:
          description: 'Already decided here'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'El negocio ya está cerrado…'
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        examples:
                          - won
                examples:
                  -
                    message: 'El negocio ya está cerrado…'
                    data:
                      status: won
      tags:
        - 'Negocios y Cotizaciones'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                external_ref:
                  type: string
                  description: 'Your identifier for the deal, or for its company.'
                  examples:
                    - sub_88213
                status:
                  type:
                    - string
                    - 'null'
                  description: 'One of `won` or `lost`. Defaults to `won`.'
                  examples:
                    - won
                lost_reason:
                  type:
                    - string
                    - 'null'
                  description: 'Required when `status` is `lost`.'
                  examples:
                    - 'Se fue con la competencia'
                accepted_quote_ids:
                  type: array
                  description: 'Which live quotes the customer actually took (D26). Omitted means none of them did, which is a valid answer.'
                  items:
                    type: integer
                  examples:
                    -
                      - 15
                amount:
                  type:
                    - string
                    - 'null'
                  description: 'Record a payment of this size at the same time.'
                  examples:
                    - '25013.94'
                paid_at:
                  type:
                    - string
                    - 'null'
                  description: 'When the money arrived. Defaults to now.'
                  examples:
                    - '2026-08-02'
                reference:
                  type:
                    - string
                    - 'null'
                  description: 'Bank or charge reference.'
                  examples:
                    - SPEI-8891
                payment_external_ref:
                  type:
                    - string
                    - 'null'
                  description: 'Your identifier for the payment.'
                  examples:
                    - charge_9912
              required:
                - external_ref
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/v1/deals/reconcile\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Idempotency-Key: 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\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"external_ref\\\": \\\"sub_88213\\\",\n    \\\"status\\\": \\\"won\\\",\n    \\\"lost_reason\\\": \\\"Se fue con la competencia\\\",\n    \\\"accepted_quote_ids\\\": [\n        15\n    ],\n    \\\"amount\\\": \\\"25013.94\\\",\n    \\\"paid_at\\\": \\\"2026-08-02\\\",\n    \\\"reference\\\": \\\"SPEI-8891\\\",\n    \\\"payment_external_ref\\\": \\\"charge_9912\\\"\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/deals/reconcile\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Idempotency-Key\": \"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\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"external_ref\": \"sub_88213\",\n    \"status\": \"won\",\n    \"lost_reason\": \"Se fue con la competencia\",\n    \"accepted_quote_ids\": [\n        15\n    ],\n    \"amount\": \"25013.94\",\n    \"paid_at\": \"2026-08-02\",\n    \"reference\": \"SPEI-8891\",\n    \"payment_external_ref\": \"charge_9912\"\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/deals/reconcile';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Idempotency-Key' => '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',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'external_ref' => 'sub_88213',\n            'status' => 'won',\n            'lost_reason' => 'Se fue con la competencia',\n            'accepted_quote_ids' => [15],\n            'amount' => '25013.94',\n            'paid_at' => '2026-08-02',\n            'reference' => 'SPEI-8891',\n            'payment_external_ref' => 'charge_9912',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/deals/reconcile'\npayload = {\n    \"external_ref\": \"sub_88213\",\n    \"status\": \"won\",\n    \"lost_reason\": \"Se fue con la competencia\",\n    \"accepted_quote_ids\": [\n        15\n    ],\n    \"amount\": \"25013.94\",\n    \"paid_at\": \"2026-08-02\",\n    \"reference\": \"SPEI-8891\",\n    \"payment_external_ref\": \"charge_9912\"\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Idempotency-Key': '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',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  '/api/v1/deals/{deal_ulid}/external-ref':
    post:
      summary: 'Link a deal to your identifier'
      operationId: linkADealToYourIdentifier
      description: "Attaches your own identifier to a deal that already exists — for the ones\nthat predate the integration. One deal,\none `external_ref`, unique inside the location."
      parameters:
        -
          in: header
          name: Idempotency-Key
          description: ''
          schema:
            type: string
            examples:
              - 'required A unique value per operation. Example: link-88213'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        examples:
                          - 1
                      ulid:
                        type: string
                        examples:
                          - 01KYDKV7N1RMWVK8H79M9H20V1
                      title:
                        type: string
                        examples:
                          - 'ADPA — Paquete 1,100 firmas'
                      description:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      status:
                        type: string
                        examples:
                          - open
                      status_label:
                        type: string
                        examples:
                          - Abierto
                      amount:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 250140000
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '25014.0000'
                          formatted:
                            type: string
                            examples:
                              - '$25,014.00'
                      paid:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 0
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '0.0000'
                          formatted:
                            type: string
                            examples:
                              - $0.00
                      balance:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 250140000
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '25014.0000'
                          formatted:
                            type: string
                            examples:
                              - '$25,014.00'
                      weighted_amount:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 100056000
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '10005.6000'
                          formatted:
                            type: string
                            examples:
                              - '$10,005.60'
                      currency:
                        type: string
                        examples:
                          - MXN
                      pipeline_id:
                        type: integer
                        examples:
                          - 1
                      pipeline_stage_id:
                        type: integer
                        examples:
                          - 2
                      stage:
                        type: object
                        properties:
                          id:
                            type: integer
                            examples:
                              - 2
                          name:
                            type: string
                            examples:
                              - 'Cotización enviada'
                          probability:
                            type: integer
                            examples:
                              - 40
                          is_won:
                            type: boolean
                            examples:
                              - false
                          is_lost:
                            type: boolean
                            examples:
                              - false
                      company_id:
                        type: integer
                        examples:
                          - 1
                      primary_contact_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      owner_id:
                        type: integer
                        examples:
                          - 26
                      expected_close_date:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      closed_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      lost_reason:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      source:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      attribution:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      external_ref:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type: string
                        examples:
                          - '2026-07-25T03:58:03+00:00'
                      updated_at:
                        type: string
                        examples:
                          - '2026-07-25T03:58:03+00:00'
                examples:
                  -
                    data:
                      id: 1
                      ulid: 01KYDKV7N1RMWVK8H79M9H20V1
                      title: 'ADPA — 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ón 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'
      tags:
        - 'Negocios y Cotizaciones'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                external_ref:
                  type: string
                  description: 'Your identifier.'
                  examples:
                    - sub_88213
              required:
                - external_ref
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/v1/deals/01JZ8Z0ZP0000000000000000/external-ref\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Idempotency-Key: required A unique value per operation. Example: link-88213\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"external_ref\\\": \\\"sub_88213\\\"\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/deals/01JZ8Z0ZP0000000000000000/external-ref\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Idempotency-Key\": \"required A unique value per operation. Example: link-88213\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"external_ref\": \"sub_88213\"\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/deals/01JZ8Z0ZP0000000000000000/external-ref';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Idempotency-Key' => 'required A unique value per operation. Example: link-88213',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'external_ref' => 'sub_88213',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/deals/01JZ8Z0ZP0000000000000000/external-ref'\npayload = {\n    \"external_ref\": \"sub_88213\"\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Idempotency-Key': 'required A unique value per operation. Example: link-88213',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
    parameters:
      -
        in: path
        name: deal_ulid
        description: 'Deal ULID.'
        required: true
        schema:
          type: string
          examples:
            - 01JZ8Z0ZP0000000000000000
  '/api/v1/deals/{ulid}':
    get:
      summary: 'Fetch a deal'
      operationId: fetchADeal
      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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        examples:
                          - 1
                      ulid:
                        type: string
                        examples:
                          - 01KYDKV7N1RMWVK8H79M9H20V1
                      title:
                        type: string
                        examples:
                          - 'ADPA — Paquete 1,100 firmas'
                      description:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      status:
                        type: string
                        examples:
                          - open
                      status_label:
                        type: string
                        examples:
                          - Abierto
                      amount:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 250140000
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '25014.0000'
                          formatted:
                            type: string
                            examples:
                              - '$25,014.00'
                      paid:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 0
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '0.0000'
                          formatted:
                            type: string
                            examples:
                              - $0.00
                      balance:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 250140000
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '25014.0000'
                          formatted:
                            type: string
                            examples:
                              - '$25,014.00'
                      weighted_amount:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 100056000
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '10005.6000'
                          formatted:
                            type: string
                            examples:
                              - '$10,005.60'
                      currency:
                        type: string
                        examples:
                          - MXN
                      pipeline_id:
                        type: integer
                        examples:
                          - 1
                      pipeline_stage_id:
                        type: integer
                        examples:
                          - 2
                      stage:
                        type: object
                        properties:
                          id:
                            type: integer
                            examples:
                              - 2
                          name:
                            type: string
                            examples:
                              - 'Cotización enviada'
                          probability:
                            type: integer
                            examples:
                              - 40
                          is_won:
                            type: boolean
                            examples:
                              - false
                          is_lost:
                            type: boolean
                            examples:
                              - false
                      company_id:
                        type: integer
                        examples:
                          - 1
                      primary_contact_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      owner_id:
                        type: integer
                        examples:
                          - 26
                      expected_close_date:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      closed_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      lost_reason:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      source:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      attribution:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      external_ref:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type: string
                        examples:
                          - '2026-07-25T03:58:03+00:00'
                      updated_at:
                        type: string
                        examples:
                          - '2026-07-25T03:58:03+00:00'
                examples:
                  -
                    data:
                      id: 1
                      ulid: 01KYDKV7N1RMWVK8H79M9H20V1
                      title: 'ADPA — 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ón 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'
      tags:
        - 'Negocios y Cotizaciones'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/v1/deals/01JZ8Z0ZP0000000000000000\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/deals/01JZ8Z0ZP0000000000000000\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/deals/01JZ8Z0ZP0000000000000000';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/deals/01JZ8Z0ZP0000000000000000'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: ulid
        description: 'Deal ULID (a numeric id still resolves).'
        required: true
        schema:
          type: string
          examples:
            - 01JZ8Z0ZP0000000000000000
  /api/v1/quotes:
    get:
      summary: 'List quotes'
      operationId: listQuotes
      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 — 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."
      parameters:
        -
          in: query
          name: deal_id
          description: "Only this deal's quotes."
          required: false
          schema:
            type: integer
            description: "Only this deal's quotes."
            examples:
              - 7
        -
          in: query
          name: status
          description: 'One of `draft`, `shared`, `viewed`, `accepted`, `rejected`, `withdrawn`, `expired`, `superseded`.'
          required: false
          schema:
            type: string
            description: 'One of `draft`, `shared`, `viewed`, `accepted`, `rejected`, `withdrawn`, `expired`, `superseded`.'
            examples:
              - shared
        -
          in: query
          name: folio
          description: 'The dictated code, with or without prefix or dash.'
          required: false
          schema:
            type: string
            description: 'The dictated code, with or without prefix or dash.'
            examples:
              - COT-7K3M9
        -
          in: query
          name: per_page
          description: 'Rows per page. Default 50, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
          required: false
          schema:
            type: integer
            description: 'Rows per page. Default 50, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
            examples:
              - 50
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          examples:
                            - 1
                        ulid:
                          type: string
                          examples:
                            - 01KYDKV7P4RVYJZZ6JNAJ521YR
                        deal_id:
                          type: integer
                          examples:
                            - 15
                        company_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        contact_id:
                          type: integer
                          examples:
                            - 6295
                        owner_id:
                          type: integer
                          examples:
                            - 26
                        quote_template_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        folio:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        reference:
                          type: string
                          examples:
                            - Borrador
                        version:
                          type: integer
                          examples:
                            - 1
                        title:
                          type: string
                          examples:
                            - Patito
                        intro:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        status:
                          type: string
                          examples:
                            - draft
                        status_label:
                          type: string
                          examples:
                            - Borrador
                        is_option:
                          type: boolean
                          examples:
                            - false
                        currency:
                          type: string
                          examples:
                            - MXN
                        subtotal:
                          type: object
                          properties:
                            amount:
                              type: integer
                              examples:
                                - 0
                            currency:
                              type: string
                              examples:
                                - MXN
                            decimal:
                              type: string
                              examples:
                                - '0.0000'
                            formatted:
                              type: string
                              examples:
                                - $0.00
                        discount_total:
                          type: object
                          properties:
                            amount:
                              type: integer
                              examples:
                                - 0
                            currency:
                              type: string
                              examples:
                                - MXN
                            decimal:
                              type: string
                              examples:
                                - '0.0000'
                            formatted:
                              type: string
                              examples:
                                - $0.00
                        tax_total:
                          type: object
                          properties:
                            amount:
                              type: integer
                              examples:
                                - 0
                            currency:
                              type: string
                              examples:
                                - MXN
                            decimal:
                              type: string
                              examples:
                                - '0.0000'
                            formatted:
                              type: string
                              examples:
                                - $0.00
                        total:
                          type: object
                          properties:
                            amount:
                              type: integer
                              examples:
                                - 0
                            currency:
                              type: string
                              examples:
                                - MXN
                            decimal:
                              type: string
                              examples:
                                - '0.0000'
                            formatted:
                              type: string
                              examples:
                                - $0.00
                        valid_until:
                          type: string
                          examples:
                            - '2026-08-09'
                        shared_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        decided_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        snapshot_hash:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        external_ref:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        pdf_url:
                          type: string
                          examples:
                            - 'http://klozzo.com/api/v1/quotes/01KYDKV7P4RVYJZZ6JNAJ521YR/pdf/signed?893456000&signature=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2'
                        created_at:
                          type: string
                          examples:
                            - '2026-07-25T18:11:14+00:00'
                        updated_at:
                          type: string
                          examples:
                            - '2026-07-25T18:11:14+00:00'
                    examples:
                      -
                        -
                          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'
                examples:
                  -
                    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'
      tags:
        - 'Negocios y Cotizaciones'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/v1/quotes?deal_id=7&status=shared&folio=COT-7K3M9&per_page=50\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/quotes\"\n);\n\nconst params = {\n    \"deal_id\": \"7\",\n    \"status\": \"shared\",\n    \"folio\": \"COT-7K3M9\",\n    \"per_page\": \"50\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/quotes';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'deal_id' => '7',\n            'status' => 'shared',\n            'folio' => 'COT-7K3M9',\n            'per_page' => '50',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/quotes'\nparams = {\n  'deal_id': '7',\n  'status': 'shared',\n  'folio': 'COT-7K3M9',\n  'per_page': '50',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers, params=params)\nresponse.json()"
    post:
      summary: 'Create a quote'
      operationId: createAQuote
      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)."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        examples:
                          - 1
                      ulid:
                        type: string
                        examples:
                          - 01KYDKV7P4RVYJZZ6JNAJ521YR
                      deal_id:
                        type: integer
                        examples:
                          - 15
                      company_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      contact_id:
                        type: integer
                        examples:
                          - 6295
                      owner_id:
                        type: integer
                        examples:
                          - 26
                      quote_template_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      folio:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      reference:
                        type: string
                        examples:
                          - Borrador
                      version:
                        type: integer
                        examples:
                          - 1
                      title:
                        type: string
                        examples:
                          - Patito
                      intro:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      status:
                        type: string
                        examples:
                          - draft
                      status_label:
                        type: string
                        examples:
                          - Borrador
                      is_option:
                        type: boolean
                        examples:
                          - false
                      currency:
                        type: string
                        examples:
                          - MXN
                      subtotal:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 0
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '0.0000'
                          formatted:
                            type: string
                            examples:
                              - $0.00
                      discount_total:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 0
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '0.0000'
                          formatted:
                            type: string
                            examples:
                              - $0.00
                      tax_total:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 0
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '0.0000'
                          formatted:
                            type: string
                            examples:
                              - $0.00
                      total:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 0
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '0.0000'
                          formatted:
                            type: string
                            examples:
                              - $0.00
                      valid_until:
                        type: string
                        examples:
                          - '2026-08-09'
                      shared_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      decided_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      snapshot_hash:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      external_ref:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      pdf_url:
                        type: string
                        examples:
                          - 'http://klozzo.com/api/v1/quotes/01KYDKV7P4RVYJZZ6JNAJ521YR/pdf/signed?893456000&signature=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2'
                      created_at:
                        type: string
                        examples:
                          - '2026-07-25T18:11:14+00:00'
                      updated_at:
                        type: string
                        examples:
                          - '2026-07-25T18:11:14+00:00'
                examples:
                  -
                    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'
      tags:
        - 'Negocios y Cotizaciones'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                deal_id:
                  type: integer
                  description: 'The deal this offer belongs to.'
                  examples:
                    - 7
                title:
                  type: string
                  description: ''
                  examples:
                    - 'Firmado Electrónico'
                intro:
                  type: string
                  description: 'Opening paragraph, may carry `{{quote.*}}` variables.'
                  examples:
                    - null
                valid_until:
                  type: string
                  description: "Commercial validity. Defaults to the location's setting."
                  examples:
                    - '2026-08-14'
                is_option:
                  type: boolean
                  description: 'Mark it when the customer will choose between several (D25).'
                  examples:
                    - false
                company_id:
                  type: integer
                  description: ''
                  examples:
                    - 12
                contact_id:
                  type: integer
                  description: ''
                  examples:
                    - 340
                quote_template_id:
                  type: integer
                  description: 'The design to print with.'
                  examples:
                    - 3
                items:
                  type: array
                  description: 'The lines. Totals are derived from them.'
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: ''
                        examples:
                          - 'Costo de las firmas por volumen'
                      quantity:
                        type: string
                        description: ''
                        examples:
                          - '1100'
                      unit_price:
                        type: string
                        description: 'Up to four decimals.'
                        examples:
                          - '19.6034'
                      unit_label:
                        type: string
                        description: ''
                        examples:
                          - firma
                      tax_rate_id:
                        type: integer
                        description: 'A tax rate of this location.'
                        examples:
                          - 1
                      discount_percent:
                        type: string
                        description: ''
                        examples:
                          - '0'
                      is_informational:
                        type: boolean
                        description: 'Shows a price and adds nothing.'
                        examples:
                          - false
                      attributes:
                        type: object
                        description: 'The service''s own columns, e.g. `{"tokens_por_validacion": 3}`.'
                        properties: {  }
                        examples:
                          - null
                    required:
                      - name
                      - quantity
                      - unit_price
                  examples:
                    -
                      - []
              required:
                - deal_id
                - title
                - items
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/v1/quotes\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"deal_id\\\": 7,\n    \\\"title\\\": \\\"Firmado Electrónico\\\",\n    \\\"valid_until\\\": \\\"2026-08-14\\\",\n    \\\"is_option\\\": false,\n    \\\"company_id\\\": 12,\n    \\\"contact_id\\\": 340,\n    \\\"quote_template_id\\\": 3,\n    \\\"items\\\": [\n        {\n            \\\"name\\\": \\\"Costo de las firmas por volumen\\\",\n            \\\"quantity\\\": \\\"1100\\\",\n            \\\"unit_price\\\": \\\"19.6034\\\",\n            \\\"unit_label\\\": \\\"firma\\\",\n            \\\"tax_rate_id\\\": 1,\n            \\\"discount_percent\\\": \\\"0\\\",\n            \\\"is_informational\\\": false\n        }\n    ]\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/quotes\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"deal_id\": 7,\n    \"title\": \"Firmado Electrónico\",\n    \"valid_until\": \"2026-08-14\",\n    \"is_option\": false,\n    \"company_id\": 12,\n    \"contact_id\": 340,\n    \"quote_template_id\": 3,\n    \"items\": [\n        {\n            \"name\": \"Costo de las firmas por volumen\",\n            \"quantity\": \"1100\",\n            \"unit_price\": \"19.6034\",\n            \"unit_label\": \"firma\",\n            \"tax_rate_id\": 1,\n            \"discount_percent\": \"0\",\n            \"is_informational\": false\n        }\n    ]\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/quotes';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'deal_id' => 7,\n            'title' => 'Firmado Electrónico',\n            'valid_until' => '2026-08-14',\n            'is_option' => false,\n            'company_id' => 12,\n            'contact_id' => 340,\n            'quote_template_id' => 3,\n            'items' => [\n                ['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],\n            ],\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/quotes'\npayload = {\n    \"deal_id\": 7,\n    \"title\": \"Firmado Electrónico\",\n    \"valid_until\": \"2026-08-14\",\n    \"is_option\": false,\n    \"company_id\": 12,\n    \"contact_id\": 340,\n    \"quote_template_id\": 3,\n    \"items\": [\n        {\n            \"name\": \"Costo de las firmas por volumen\",\n            \"quantity\": \"1100\",\n            \"unit_price\": \"19.6034\",\n            \"unit_label\": \"firma\",\n            \"tax_rate_id\": 1,\n            \"discount_percent\": \"0\",\n            \"is_informational\": false\n        }\n    ]\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  '/api/v1/quotes/{ulid}':
    get:
      summary: 'Fetch a quote'
      operationId: fetchAQuote
      description: "Returns one quote by its ULID, with its line items and its totals. Money always comes back as\nan object — `amount` is an integer at scale 10⁴, `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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        examples:
                          - 1
                      ulid:
                        type: string
                        examples:
                          - 01KYDKV7P4RVYJZZ6JNAJ521YR
                      deal_id:
                        type: integer
                        examples:
                          - 15
                      company_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      contact_id:
                        type: integer
                        examples:
                          - 6295
                      owner_id:
                        type: integer
                        examples:
                          - 26
                      quote_template_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      folio:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      reference:
                        type: string
                        examples:
                          - Borrador
                      version:
                        type: integer
                        examples:
                          - 1
                      title:
                        type: string
                        examples:
                          - Patito
                      intro:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      status:
                        type: string
                        examples:
                          - draft
                      status_label:
                        type: string
                        examples:
                          - Borrador
                      is_option:
                        type: boolean
                        examples:
                          - false
                      currency:
                        type: string
                        examples:
                          - MXN
                      subtotal:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 0
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '0.0000'
                          formatted:
                            type: string
                            examples:
                              - $0.00
                      discount_total:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 0
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '0.0000'
                          formatted:
                            type: string
                            examples:
                              - $0.00
                      tax_total:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 0
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '0.0000'
                          formatted:
                            type: string
                            examples:
                              - $0.00
                      total:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 0
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '0.0000'
                          formatted:
                            type: string
                            examples:
                              - $0.00
                      valid_until:
                        type: string
                        examples:
                          - '2026-08-09'
                      shared_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      decided_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      snapshot_hash:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      external_ref:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      pdf_url:
                        type: string
                        examples:
                          - 'http://klozzo.com/api/v1/quotes/01KYDKV7P4RVYJZZ6JNAJ521YR/pdf/signed?893456000&signature=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2'
                      created_at:
                        type: string
                        examples:
                          - '2026-07-25T18:11:14+00:00'
                      updated_at:
                        type: string
                        examples:
                          - '2026-07-25T18:11:14+00:00'
                examples:
                  -
                    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'
      tags:
        - 'Negocios y Cotizaciones'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/v1/quotes/01JZ8Z0ZP0000000000000000\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/quotes/01JZ8Z0ZP0000000000000000\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/quotes/01JZ8Z0ZP0000000000000000';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/quotes/01JZ8Z0ZP0000000000000000'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: ulid
        description: 'Quote ULID (a numeric id still resolves).'
        required: true
        schema:
          type: string
          examples:
            - 01JZ8Z0ZP0000000000000000
  '/api/v1/quotes/{quote_ulid}/pdf':
    get:
      summary: 'Download the quote PDF'
      operationId: downloadTheQuotePDF
      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 —\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)."
      parameters: []
      responses:
        200:
          description: PDF
          content:
            application/json:
              schema:
                type: string
                examples:
                  - '%PDF-1.7 …'
      tags:
        - 'Negocios y Cotizaciones'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/v1/quotes/01JZ8Z0ZP0000000000000000/pdf\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/quotes/01JZ8Z0ZP0000000000000000/pdf\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/quotes/01JZ8Z0ZP0000000000000000/pdf';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/quotes/01JZ8Z0ZP0000000000000000/pdf'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: quote_ulid
        description: 'Quote ULID.'
        required: true
        schema:
          type: string
          examples:
            - 01JZ8Z0ZP0000000000000000
  /api/v1/sales:
    post:
      summary: 'Record a sale'
      operationId: recordASale
      description: "Records a sale for a purchase that happened entirely on your side, with\nnobody here\nopening a deal for it — 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 — 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."
      parameters:
        -
          in: header
          name: Idempotency-Key
          description: ''
          schema:
            type: string
            examples:
              - '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'
      responses:
        200:
          description: 'Already recorded'
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      created:
                        type: boolean
                        examples:
                          - false
                      matched_by:
                        type: string
                        examples:
                          - payment_external_ref
                examples:
                  -
                    meta:
                      created: false
                      matched_by: payment_external_ref
        201:
          description: 'Nobody had attended this customer'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      deal:
                        type: object
                        properties:
                          status:
                            type: string
                            examples:
                              - won
                          owner_id:
                            type:
                              - string
                              - 'null'
                            examples:
                              - null
                  meta:
                    type: object
                    properties:
                      created:
                        type: boolean
                        examples:
                          - true
                      deal_created:
                        type: boolean
                        examples:
                          - true
                      matched_by:
                        type: string
                        examples:
                          - created
                      claimable:
                        type: boolean
                        examples:
                          - true
                examples:
                  -
                    data:
                      deal:
                        status: won
                        owner_id: null
                    meta:
                      created: true
                      deal_created: true
                      matched_by: created
                      claimable: true
        404:
          description: 'You named a deal that is not here'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No hay ningún negocio con el external_ref «sub_44».'
                examples:
                  -
                    message: 'No hay ningún negocio con el external_ref «sub_44».'
      tags:
        - 'Negocios y Cotizaciones'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                external_ref:
                  type: string
                  description: 'Your identifier for THIS sale. Recording it twice is impossible.'
                  examples:
                    - sale_88213
                amount:
                  type: string
                  description: 'What was paid. Up to four decimals, separators tolerated.'
                  examples:
                    - '1499.00'
                currency:
                  type:
                    - string
                    - 'null'
                  description: "ISO 4217. Defaults to the location's."
                  examples:
                    - MXN
                paid_at:
                  type:
                    - string
                    - 'null'
                  description: 'When the money arrived. Defaults to now.'
                  examples:
                    - '2026-08-23T10:00:00Z'
                method:
                  type:
                    - string
                    - 'null'
                  description: 'One of `transferencia`, `efectivo`, `tarjeta`, `otro`. Defaults to `tarjeta`.'
                  examples:
                    - tarjeta
                reference:
                  type:
                    - string
                    - 'null'
                  description: 'Bank or charge reference.'
                  examples:
                    - ch_9912
                title:
                  type:
                    - string
                    - 'null'
                  description: 'Title for the deal if one has to be created.'
                  examples:
                    - 'Plan Pro anual'
                deal_external_ref:
                  type:
                    - string
                    - 'null'
                  description: 'Point the sale at one specific deal. Answers 404 if that deal is not here.'
                  examples:
                    - sub_44
                customer:
                  type:
                    - object
                    - 'null'
                  description: 'Who bought. Required unless `deal_external_ref` identifies the deal.'
                  properties:
                    email:
                      type:
                        - string
                        - 'null'
                      description: ''
                      examples:
                        - ada@example.com
                    phone:
                      type:
                        - string
                        - 'null'
                      description: ''
                      examples:
                        - '+52 55 1234 5678'
                    phone_country:
                      type:
                        - string
                        - 'null'
                      description: 'Must not be greater than 2 characters.'
                      examples:
                        - kh
                    first_name:
                      type:
                        - string
                        - 'null'
                      description: ''
                      examples:
                        - Ada
                    last_name:
                      type:
                        - string
                        - 'null'
                      description: ''
                      examples:
                        - Lovelace
                    company_name:
                      type:
                        - string
                        - 'null'
                      description: ''
                      examples:
                        - ADPA
                    company_external_ref:
                      type:
                        - string
                        - 'null'
                      description: 'Your identifier for the company.'
                      examples:
                        - verificamex-99
                  examples:
                    - []
                plan:
                  type:
                    - object
                    - 'null'
                  description: 'How long what was bought lasts. Omit it for a one-off purchase.'
                  properties:
                    name:
                      type:
                        - string
                        - 'null'
                      description: ''
                      examples:
                        - 'Plan Pro'
                    product_sku:
                      type:
                        - string
                        - 'null'
                      description: 'Matches a product in the catalogue.'
                      examples:
                        - PLAN-PRO
                    external_ref:
                      type:
                        - string
                        - 'null'
                      description: 'Your identifier for the term. Sending it again EXTENDS the same term instead of opening a second one — that is how a renewal is told from a new sale.'
                      examples:
                        - sub_88213
                    starts_at:
                      type:
                        - string
                        - 'null'
                      description: 'Defaults to today.'
                      examples:
                        - '2026-08-23'
                    ends_at:
                      type:
                        - string
                        - 'null'
                      description: 'Leave both this and `term_months` out for a purchase that never expires.'
                      examples:
                        - '2027-08-23'
                    term_months:
                      type:
                        - integer
                        - 'null'
                      description: 'Used to derive `ends_at` when you do not send one.'
                      examples:
                        - 12
                    auto_renew:
                      type:
                        - boolean
                        - 'null'
                      description: 'Whether your system will renew it on its own.'
                      examples:
                        - true
                  examples:
                    - []
              required:
                - external_ref
                - amount
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/v1/sales\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Idempotency-Key: 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\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"external_ref\\\": \\\"sale_88213\\\",\n    \\\"amount\\\": \\\"1499.00\\\",\n    \\\"currency\\\": \\\"MXN\\\",\n    \\\"paid_at\\\": \\\"2026-08-23T10:00:00Z\\\",\n    \\\"method\\\": \\\"tarjeta\\\",\n    \\\"reference\\\": \\\"ch_9912\\\",\n    \\\"title\\\": \\\"Plan Pro anual\\\",\n    \\\"deal_external_ref\\\": \\\"sub_44\\\",\n    \\\"customer\\\": {\n        \\\"email\\\": \\\"ada@example.com\\\",\n        \\\"phone\\\": \\\"+52 55 1234 5678\\\",\n        \\\"phone_country\\\": \\\"kh\\\",\n        \\\"first_name\\\": \\\"Ada\\\",\n        \\\"last_name\\\": \\\"Lovelace\\\",\n        \\\"company_name\\\": \\\"ADPA\\\",\n        \\\"company_external_ref\\\": \\\"verificamex-99\\\"\n    },\n    \\\"plan\\\": {\n        \\\"name\\\": \\\"Plan Pro\\\",\n        \\\"product_sku\\\": \\\"PLAN-PRO\\\",\n        \\\"external_ref\\\": \\\"sub_88213\\\",\n        \\\"starts_at\\\": \\\"2026-08-23\\\",\n        \\\"ends_at\\\": \\\"2027-08-23\\\",\n        \\\"term_months\\\": 12,\n        \\\"auto_renew\\\": true\n    }\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/sales\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Idempotency-Key\": \"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\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"external_ref\": \"sale_88213\",\n    \"amount\": \"1499.00\",\n    \"currency\": \"MXN\",\n    \"paid_at\": \"2026-08-23T10:00:00Z\",\n    \"method\": \"tarjeta\",\n    \"reference\": \"ch_9912\",\n    \"title\": \"Plan Pro anual\",\n    \"deal_external_ref\": \"sub_44\",\n    \"customer\": {\n        \"email\": \"ada@example.com\",\n        \"phone\": \"+52 55 1234 5678\",\n        \"phone_country\": \"kh\",\n        \"first_name\": \"Ada\",\n        \"last_name\": \"Lovelace\",\n        \"company_name\": \"ADPA\",\n        \"company_external_ref\": \"verificamex-99\"\n    },\n    \"plan\": {\n        \"name\": \"Plan Pro\",\n        \"product_sku\": \"PLAN-PRO\",\n        \"external_ref\": \"sub_88213\",\n        \"starts_at\": \"2026-08-23\",\n        \"ends_at\": \"2027-08-23\",\n        \"term_months\": 12,\n        \"auto_renew\": true\n    }\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/sales';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Idempotency-Key' => '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',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'external_ref' => 'sale_88213',\n            'amount' => '1499.00',\n            'currency' => 'MXN',\n            'paid_at' => '2026-08-23T10:00:00Z',\n            'method' => 'tarjeta',\n            'reference' => 'ch_9912',\n            'title' => 'Plan Pro anual',\n            'deal_external_ref' => 'sub_44',\n            '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'],\n            '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],\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/sales'\npayload = {\n    \"external_ref\": \"sale_88213\",\n    \"amount\": \"1499.00\",\n    \"currency\": \"MXN\",\n    \"paid_at\": \"2026-08-23T10:00:00Z\",\n    \"method\": \"tarjeta\",\n    \"reference\": \"ch_9912\",\n    \"title\": \"Plan Pro anual\",\n    \"deal_external_ref\": \"sub_44\",\n    \"customer\": {\n        \"email\": \"ada@example.com\",\n        \"phone\": \"+52 55 1234 5678\",\n        \"phone_country\": \"kh\",\n        \"first_name\": \"Ada\",\n        \"last_name\": \"Lovelace\",\n        \"company_name\": \"ADPA\",\n        \"company_external_ref\": \"verificamex-99\"\n    },\n    \"plan\": {\n        \"name\": \"Plan Pro\",\n        \"product_sku\": \"PLAN-PRO\",\n        \"external_ref\": \"sub_88213\",\n        \"starts_at\": \"2026-08-23\",\n        \"ends_at\": \"2027-08-23\",\n        \"term_months\": 12,\n        \"auto_renew\": true\n    }\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Idempotency-Key': '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',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  /api/v1/payments:
    get:
      summary: 'List payments'
      operationId: listPayments
      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 — `?external_ref=` finds the\none carrying your charge identifier, which is the cheapest way to answer\n\"did that webhook land?\"."
      parameters:
        -
          in: query
          name: deal_id
          description: "Only this deal's payments."
          required: false
          schema:
            type: integer
            description: "Only this deal's payments."
            examples:
              - 7
        -
          in: query
          name: external_ref
          description: 'Find the one carrying your identifier.'
          required: false
          schema:
            type: string
            description: 'Find the one carrying your identifier.'
            examples:
              - spei-8891
        -
          in: query
          name: per_page
          description: 'Rows per page. Default 50, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
          required: false
          schema:
            type: integer
            description: 'Rows per page. Default 50, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
            examples:
              - 50
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        deal_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        quote_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        subscription_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        amount:
                          type: object
                          properties:
                            amount:
                              type: integer
                              examples:
                                - 100000000
                            currency:
                              type: string
                              examples:
                                - MXN
                            decimal:
                              type: string
                              examples:
                                - '10000.0000'
                            formatted:
                              type: string
                              examples:
                                - '$10,000.00'
                        currency:
                          type: string
                          examples:
                            - MXN
                        paid_at:
                          type: string
                          examples:
                            - '2026-08-17T02:19:50+00:00'
                        method:
                          type: string
                          examples:
                            - transferencia
                        method_label:
                          type: string
                          examples:
                            - Transferencia
                        origin:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        reference:
                          type: string
                          examples:
                            - SPEI-3724
                        note:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        recorded_by:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        external_ref:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        created_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                    examples:
                      -
                        -
                          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
                examples:
                  -
                    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
      tags:
        - 'Negocios y Cotizaciones'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/v1/payments?deal_id=7&external_ref=spei-8891&per_page=50\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/payments\"\n);\n\nconst params = {\n    \"deal_id\": \"7\",\n    \"external_ref\": \"spei-8891\",\n    \"per_page\": \"50\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/payments';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'deal_id' => '7',\n            'external_ref' => 'spei-8891',\n            'per_page' => '50',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/payments'\nparams = {\n  'deal_id': '7',\n  'external_ref': 'spei-8891',\n  'per_page': '50',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers, params=params)\nresponse.json()"
    post:
      summary: 'Record a payment'
      operationId: recordAPayment
      description: "Records a payment against a deal that already exists. It does not\nclose the deal and it does not accept a quote — 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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      deal_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      quote_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      subscription_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      amount:
                        type: object
                        properties:
                          amount:
                            type: integer
                            examples:
                              - 100000000
                          currency:
                            type: string
                            examples:
                              - MXN
                          decimal:
                            type: string
                            examples:
                              - '10000.0000'
                          formatted:
                            type: string
                            examples:
                              - '$10,000.00'
                      currency:
                        type: string
                        examples:
                          - MXN
                      paid_at:
                        type: string
                        examples:
                          - '2026-08-12T02:19:50+00:00'
                      method:
                        type: string
                        examples:
                          - transferencia
                      method_label:
                        type: string
                        examples:
                          - Transferencia
                      origin:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      reference:
                        type: string
                        examples:
                          - SPEI-0564
                      note:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      recorded_by:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      external_ref:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'A deal from another location, or none'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Deal id no es válido.'
                      errors:
                        type: object
                        properties:
                          deal_id:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Deal id no es válido.'
                    examples:
                      -
                        message: 'Deal id no es válido.'
                        errors:
                          deal_id:
                            - 'Deal id no es válido.'
                  -
                    description: 'An amount that is not a number'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Amount no es un importe válido.'
                      errors:
                        type: object
                        properties:
                          amount:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Amount no es un importe válido.'
                    examples:
                      -
                        message: 'Amount no es un importe válido.'
                        errors:
                          amount:
                            - 'Amount no es un importe válido.'
      tags:
        - 'Negocios y Cotizaciones'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                deal_id:
                  type: integer
                  description: 'The deal being paid.'
                  examples:
                    - 7
                quote_id:
                  type:
                    - integer
                    - 'null'
                  description: 'The quote it settles, when there is one.'
                  examples:
                    - 15
                amount:
                  type: string
                  description: 'Up to four decimals, separators tolerated.'
                  examples:
                    - '25013.94'
                paid_at:
                  type: string
                  description: 'When the money arrived.'
                  examples:
                    - '2026-08-02'
                method:
                  type:
                    - string
                    - 'null'
                  description: 'One of `transferencia`, `efectivo`, `tarjeta`, `otro`.'
                  examples:
                    - transferencia
                reference:
                  type:
                    - string
                    - 'null'
                  description: 'Bank reference.'
                  examples:
                    - SPEI-8891
                note:
                  type:
                    - string
                    - 'null'
                  description: ''
                  examples:
                    - 'Primer parcialidad'
                external_ref:
                  type:
                    - string
                    - 'null'
                  description: 'Your identifier for this payment.'
                  examples:
                    - charge_9912
              required:
                - deal_id
                - amount
                - paid_at
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/v1/payments\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"deal_id\\\": 7,\n    \\\"quote_id\\\": 15,\n    \\\"amount\\\": \\\"25013.94\\\",\n    \\\"paid_at\\\": \\\"2026-08-02\\\",\n    \\\"method\\\": \\\"transferencia\\\",\n    \\\"reference\\\": \\\"SPEI-8891\\\",\n    \\\"note\\\": \\\"Primer parcialidad\\\",\n    \\\"external_ref\\\": \\\"charge_9912\\\"\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/payments\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"deal_id\": 7,\n    \"quote_id\": 15,\n    \"amount\": \"25013.94\",\n    \"paid_at\": \"2026-08-02\",\n    \"method\": \"transferencia\",\n    \"reference\": \"SPEI-8891\",\n    \"note\": \"Primer parcialidad\",\n    \"external_ref\": \"charge_9912\"\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/payments';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'deal_id' => 7,\n            'quote_id' => 15,\n            'amount' => '25013.94',\n            'paid_at' => '2026-08-02',\n            'method' => 'transferencia',\n            'reference' => 'SPEI-8891',\n            'note' => 'Primer parcialidad',\n            'external_ref' => 'charge_9912',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/payments'\npayload = {\n    \"deal_id\": 7,\n    \"quote_id\": 15,\n    \"amount\": \"25013.94\",\n    \"paid_at\": \"2026-08-02\",\n    \"method\": \"transferencia\",\n    \"reference\": \"SPEI-8891\",\n    \"note\": \"Primer parcialidad\",\n    \"external_ref\": \"charge_9912\"\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  /api/documents/heartbeat:
    post:
      summary: 'Report reading time on a shared document'
      operationId: reportReadingTimeOnASharedDocument
      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 — 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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    examples:
                      - true
                  is_valid:
                    type: boolean
                    examples:
                      - true
                  is_completed:
                    type: boolean
                    examples:
                      - false
                examples:
                  -
                    ok: true
                    is_valid: true
                    is_completed: false
        404:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    examples:
                      - false
                examples:
                  -
                    ok: false
        422:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'The session token field is required.'
                  errors:
                    type: object
                    properties:
                      session_token:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - 'The session token field is required.'
                examples:
                  -
                    message: 'The session token field is required.'
                    errors:
                      session_token:
                        - 'The session token field is required.'
      tags:
        - Documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                session_token:
                  type: string
                  description: 'The token the viewer received when the shared link was opened.'
                  examples:
                    - 01JAX2Q7K6MPQ4S5V8W9YZBCDE
                page_number:
                  type: integer
                  description: 'The page being read, starting at 1.'
                  examples:
                    - 3
                visible:
                  type: boolean
                  description: 'Whether the document is on screen right now. A hidden tab adds no time.'
                  examples:
                    - true
              required:
                - session_token
                - page_number
                - visible
      security: []
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/documents/heartbeat\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"session_token\\\": \\\"01JAX2Q7K6MPQ4S5V8W9YZBCDE\\\",\n    \\\"page_number\\\": 3,\n    \\\"visible\\\": true\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/documents/heartbeat\"\n);\n\nconst headers = {\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"session_token\": \"01JAX2Q7K6MPQ4S5V8W9YZBCDE\",\n    \"page_number\": 3,\n    \"visible\": true\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/documents/heartbeat';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'session_token' => '01JAX2Q7K6MPQ4S5V8W9YZBCDE',\n            'page_number' => 3,\n            'visible' => true,\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/documents/heartbeat'\npayload = {\n    \"session_token\": \"01JAX2Q7K6MPQ4S5V8W9YZBCDE\",\n    \"page_number\": 3,\n    \"visible\": true\n}\nheaders = {\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  /api/imports:
    get:
      summary: 'List imports'
      operationId: listImports
      description: 'Returns paginated import jobs owned by the authenticated user, newest first.'
      parameters:
        -
          in: query
          name: per_page
          description: 'Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
          required: false
          schema:
            type: integer
            description: 'Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
            examples:
              - 20
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        type:
                          type: string
                          examples:
                            - contacts
                        file_name:
                          type: string
                          examples:
                            - adipisci.csv
                        status:
                          type: string
                          examples:
                            - pending
                        total_rows:
                          type: integer
                          examples:
                            - 0
                        processed_rows:
                          type: integer
                          examples:
                            - 0
                        succeeded_rows:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        failed_rows:
                          type: integer
                          examples:
                            - 0
                        column_mapping:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        duplicate_handling:
                          type: string
                          examples:
                            - skip
                        errors:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        error_file_available:
                          type: boolean
                          examples:
                            - false
                        progress_percentage:
                          type: integer
                          examples:
                            - 0
                        started_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        finished_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        completed_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        created_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        updated_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                    examples:
                      -
                        -
                          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:
                    type: object
                    properties:
                      first:
                        type: string
                        examples:
                          - '/?page=1'
                      last:
                        type: string
                        examples:
                          - '/?page=1'
                      prev:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      next:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        examples:
                          - 1
                      from:
                        type: integer
                        examples:
                          - 1
                      last_page:
                        type: integer
                        examples:
                          - 1
                      links:
                        type: array
                        items:
                          type: object
                          properties:
                            url:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            label:
                              type: string
                              examples:
                                - '&laquo; Previous'
                            page:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            active:
                              type: boolean
                              examples:
                                - false
                        examples:
                          -
                            -
                              url: null
                              label: '&laquo; Previous'
                              page: null
                              active: false
                            -
                              url: '/?page=1'
                              label: '1'
                              page: 1
                              active: true
                            -
                              url: null
                              label: 'Next &raquo;'
                              page: null
                              active: false
                      path:
                        type: string
                        examples:
                          - /
                      per_page:
                        type: integer
                        examples:
                          - 20
                      to:
                        type: integer
                        examples:
                          - 2
                      total:
                        type: integer
                        examples:
                          - 2
                examples:
                  -
                    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: '&laquo; Previous'
                          page: null
                          active: false
                        -
                          url: '/?page=1'
                          label: '1'
                          page: 1
                          active: true
                        -
                          url: null
                          label: 'Next &raquo;'
                          page: null
                          active: false
                      path: /
                      per_page: 20
                      to: 2
                      total: 2
      tags:
        - Imports
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/imports?per_page=20\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/imports\"\n);\n\nconst params = {\n    \"per_page\": \"20\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/imports';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'per_page' => '20',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/imports'\nparams = {\n  'per_page': '20',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers, params=params)\nresponse.json()"
    post:
      summary: 'Create an import'
      operationId: createAnImport
      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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      type:
                        type: string
                        examples:
                          - contacts
                      file_name:
                        type: string
                        examples:
                          - eius.csv
                      status:
                        type: string
                        examples:
                          - pending
                      total_rows:
                        type: integer
                        examples:
                          - 0
                      processed_rows:
                        type: integer
                        examples:
                          - 0
                      succeeded_rows:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      failed_rows:
                        type: integer
                        examples:
                          - 0
                      column_mapping:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      duplicate_handling:
                        type: string
                        examples:
                          - skip
                      errors:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      error_file_available:
                        type: boolean
                        examples:
                          - false
                      progress_percentage:
                        type: integer
                        examples:
                          - 0
                      started_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      finished_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      completed_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'A file type that is not accepted'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'File debe ser un archivo de tipo: csv, txt, xlsx, xls.'
                      errors:
                        type: object
                        properties:
                          file:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'File debe ser un archivo de tipo: csv, txt, xlsx, xls.'
                    examples:
                      -
                        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.'
                  -
                    description: 'Over 10 MB'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'File no puede pesar más de 10240 kilobytes.'
                      errors:
                        type: object
                        properties:
                          file:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'File no puede pesar más de 10240 kilobytes.'
                    examples:
                      -
                        message: 'File no puede pesar más de 10240 kilobytes.'
                        errors:
                          file:
                            - 'File no puede pesar más de 10240 kilobytes.'
                  -
                    description: 'Nothing to import'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Falta type.'
                      errors:
                        type: object
                        properties:
                          type:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Falta type.'
                    examples:
                      -
                        message: 'Falta type.'
                        errors:
                          type:
                            - 'Falta type.'
      tags:
        - Imports
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: 'What to import. One of `contacts`, `leads`, `companies`.'
                  examples:
                    - contacts
                file:
                  type: string
                  format: binary
                  description: 'CSV, TXT, XLSX, or XLS. Max 10 MB.'
                column_mapping:
                  type:
                    - object
                    - 'null'
                  description: 'Map of `csv_column_name => contact_field_name`. Required for non-conventional headers.'
                  properties: {  }
                  examples:
                    - []
                duplicate_handling:
                  type:
                    - string
                    - 'null'
                  description: 'Action on collision. One of `skip` (default), `update`, `create`.'
                  examples:
                    - skip
                location_id:
                  type:
                    - integer
                    - 'null'
                  description: 'Scope the import to a specific location.'
                  examples:
                    - 1
              required:
                - type
                - file
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/imports\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: multipart/form-data\" \\\n    --header \"Accept: application/json\" \\\n    --form \"type=contacts\"\\\n    --form \"duplicate_handling=skip\"\\\n    --form \"location_id=1\"\\\n    --form \"file=@/private/var/folders/yw/tssyhl110hs29p29scc2m0jc0000gn/T/phpi0k13cg52dh7d0QJtkp\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/imports\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"multipart/form-data\",\n    \"Accept\": \"application/json\",\n};\n\nconst body = new FormData();\nbody.append('type', 'contacts');\nbody.append('duplicate_handling', 'skip');\nbody.append('location_id', '1');\nbody.append('file', document.querySelector('input[name=\"file\"]').files[0]);\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/imports';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'multipart/form-data',\n            'Accept' => 'application/json',\n        ],\n        'multipart' => [\n            [\n                'name' => 'type',\n                'contents' => 'contacts'\n            ],\n            [\n                'name' => 'duplicate_handling',\n                'contents' => 'skip'\n            ],\n            [\n                'name' => 'location_id',\n                'contents' => '1'\n            ],\n            [\n                'name' => 'file',\n                'contents' => fopen('/private/var/folders/yw/tssyhl110hs29p29scc2m0jc0000gn/T/phpi0k13cg52dh7d0QJtkp', 'r')\n            ],\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/imports'\nfiles = {\n  'type': (None, 'contacts'),\n  'duplicate_handling': (None, 'skip'),\n  'location_id': (None, '1'),\n  'file': open('/private/var/folders/yw/tssyhl110hs29p29scc2m0jc0000gn/T/phpi0k13cg52dh7d0QJtkp', 'rb')}\npayload = {\n    \"type\": \"contacts\",\n    \"column_mapping\": [],\n    \"duplicate_handling\": \"skip\",\n    \"location_id\": 1\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'multipart/form-data',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, files=files)\nresponse.json()"
  '/api/imports/{id}':
    get:
      summary: 'Fetch an import'
      operationId: fetchAnImport
      description: "Returns one import by id, with its full payload and the original column\nmapping. For lightweight progress\npolling, prefer `status` instead."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      type:
                        type: string
                        examples:
                          - contacts
                      file_name:
                        type: string
                        examples:
                          - adipisci.csv
                      status:
                        type: string
                        examples:
                          - pending
                      total_rows:
                        type: integer
                        examples:
                          - 0
                      processed_rows:
                        type: integer
                        examples:
                          - 0
                      succeeded_rows:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      failed_rows:
                        type: integer
                        examples:
                          - 0
                      column_mapping:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      duplicate_handling:
                        type: string
                        examples:
                          - skip
                      errors:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      error_file_available:
                        type: boolean
                        examples:
                          - false
                      progress_percentage:
                        type: integer
                        examples:
                          - 0
                      started_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      finished_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      completed_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
      tags:
        - Imports
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/imports/17\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/imports/17\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/imports/17';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/imports/17'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    delete:
      summary: 'Delete an import'
      operationId: deleteAnImport
      description: "Removes the import record and original upload from disk. Imported contacts\nare NOT removed."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Import deleted.'
                examples:
                  -
                    message: 'Import deleted.'
      tags:
        - Imports
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request DELETE \\\n    \"https://klozzo.com/api/imports/17\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/imports/17\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"DELETE\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/imports/17';\n$response = $client->delete(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/imports/17'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('DELETE', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: id
        description: 'Import ID.'
        required: true
        schema:
          type: integer
          examples:
            - 17
  '/api/imports/{import_id}/status':
    get:
      summary: 'Import progress'
      operationId: importProgress
      description: "Returns the progress of one import in about a kilobyte, meant for polling.\nCall every 2–5 s\nuntil `status` is `completed` or `failed`."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    examples:
                      - 17
                  status:
                    type: string
                    examples:
                      - processing
                  total_rows:
                    type: integer
                    examples:
                      - 1500
                  processed_rows:
                    type: integer
                    examples:
                      - 420
                  succeeded_rows:
                    type: integer
                    examples:
                      - 415
                  failed_rows:
                    type: integer
                    examples:
                      - 5
                  progress_percentage:
                    type: integer
                    examples:
                      - 28
                  errors:
                    type:
                      - string
                      - 'null'
                    examples:
                      - null
                  error_file_available:
                    type: boolean
                    examples:
                      - false
                  started_at:
                    type: string
                    examples:
                      - '2026-06-05T13:42:00+00:00'
                  finished_at:
                    type:
                      - string
                      - 'null'
                    examples:
                      - null
                  completed_at:
                    type:
                      - string
                      - 'null'
                    examples:
                      - null
                examples:
                  -
                    id: 17
                    status: processing
                    total_rows: 1500
                    processed_rows: 420
                    succeeded_rows: 415
                    failed_rows: 5
                    progress_percentage: 28
                    errors: null
                    error_file_available: false
                    started_at: '2026-06-05T13:42:00+00:00'
                    finished_at: null
                    completed_at: null
      tags:
        - Imports
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/imports/17/status\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/imports/17/status\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/imports/17/status';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/imports/17/status'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: import_id
        description: 'Import ID.'
        required: true
        schema:
          type: integer
          examples:
            - 17
  '/api/imports/{import_id}/errors':
    get:
      summary: 'Download error CSV'
      operationId: downloadErrorCSV
      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."
      parameters: []
      responses:
        200:
          description: 'streamed CSV download'
          content:
            application/json:
              schema:
                type: string
                examples:
                  - '<binary CSV>'
        404:
          description: 'no error file'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No error file'
                examples:
                  -
                    message: 'No error file'
      tags:
        - Imports
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/imports/17/errors\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/imports/17/errors\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/imports/17/errors';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/imports/17/errors'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: import_id
        description: 'Import ID.'
        required: true
        schema:
          type: integer
          examples:
            - 17
  /api/exports:
    get:
      summary: 'List exports'
      operationId: listExports
      description: 'Returns paginated export jobs owned by the authenticated user, newest first.'
      parameters:
        -
          in: query
          name: per_page
          description: 'Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
          required: false
          schema:
            type: integer
            description: 'Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
            examples:
              - 20
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        format:
                          type: string
                          examples:
                            - csv
                        status:
                          type: string
                          examples:
                            - pending
                        total_rows:
                          type: integer
                          examples:
                            - 0
                        file_name:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        filters:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        columns:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        error:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        started_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        finished_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        expires_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        created_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        download_url:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                    examples:
                      -
                        -
                          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:
                    type: object
                    properties:
                      first:
                        type: string
                        examples:
                          - '/?page=1'
                      last:
                        type: string
                        examples:
                          - '/?page=1'
                      prev:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      next:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        examples:
                          - 1
                      from:
                        type: integer
                        examples:
                          - 1
                      last_page:
                        type: integer
                        examples:
                          - 1
                      links:
                        type: array
                        items:
                          type: object
                          properties:
                            url:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            label:
                              type: string
                              examples:
                                - '&laquo; Previous'
                            page:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            active:
                              type: boolean
                              examples:
                                - false
                        examples:
                          -
                            -
                              url: null
                              label: '&laquo; Previous'
                              page: null
                              active: false
                            -
                              url: '/?page=1'
                              label: '1'
                              page: 1
                              active: true
                            -
                              url: null
                              label: 'Next &raquo;'
                              page: null
                              active: false
                      path:
                        type: string
                        examples:
                          - /
                      per_page:
                        type: integer
                        examples:
                          - 20
                      to:
                        type: integer
                        examples:
                          - 2
                      total:
                        type: integer
                        examples:
                          - 2
                examples:
                  -
                    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: '&laquo; Previous'
                          page: null
                          active: false
                        -
                          url: '/?page=1'
                          label: '1'
                          page: 1
                          active: true
                        -
                          url: null
                          label: 'Next &raquo;'
                          page: null
                          active: false
                      path: /
                      per_page: 20
                      to: 2
                      total: 2
      tags:
        - Exports
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/exports?per_page=20\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/exports\"\n);\n\nconst params = {\n    \"per_page\": \"20\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/exports';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'per_page' => '20',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/exports'\nparams = {\n  'per_page': '20',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers, params=params)\nresponse.json()"
    post:
      summary: 'Create an export'
      operationId: createAnExport
      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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      format:
                        type: string
                        examples:
                          - csv
                      status:
                        type: string
                        examples:
                          - pending
                      total_rows:
                        type: integer
                        examples:
                          - 0
                      file_name:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      filters:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      columns:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      error:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      started_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      finished_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      expires_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      download_url:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'A format that does not exist'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Format no es una opción válida.'
                      errors:
                        type: object
                        properties:
                          format:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Format no es una opción válida.'
                    examples:
                      -
                        message: 'Format no es una opción válida.'
                        errors:
                          format:
                            - 'Format no es una opción válida.'
                  -
                    description: 'A column that is not a column'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Columns.0 no puede tener más de 64 caracteres.'
                      errors:
                        type: object
                        properties:
                          columns.0:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Columns.0 no puede tener más de 64 caracteres.'
                    examples:
                      -
                        message: 'Columns.0 no puede tener más de 64 caracteres.'
                        errors:
                          columns.0:
                            - 'Columns.0 no puede tener más de 64 caracteres.'
      tags:
        - Exports
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                format:
                  type:
                    - string
                    - 'null'
                  description: 'Output format. One of `csv` (default), `xlsx`.'
                  examples:
                    - csv
                filters:
                  type:
                    - object
                    - 'null'
                  description: 'Same shape as smart-list filters; restrict the export to matching rows.'
                  properties: {  }
                  examples:
                    - []
                columns:
                  type: array
                  description: 'Whitelist of contact columns to include. Omit to use the default set.'
                  items:
                    type: string
                  examples:
                    -
                      - first_name
                      - last_name
                      - email
                location_id:
                  type:
                    - integer
                    - 'null'
                  description: 'Scope the export to a specific location.'
                  examples:
                    - 1
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/exports\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"format\\\": \\\"csv\\\",\n    \\\"filters\\\": [],\n    \\\"columns\\\": [\n        \\\"first_name\\\",\n        \\\"last_name\\\",\n        \\\"email\\\"\n    ],\n    \\\"location_id\\\": 1\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/exports\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"format\": \"csv\",\n    \"filters\": [],\n    \"columns\": [\n        \"first_name\",\n        \"last_name\",\n        \"email\"\n    ],\n    \"location_id\": 1\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/exports';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'format' => 'csv',\n            'filters' => [],\n            'columns' => ['first_name', 'last_name', 'email'],\n            'location_id' => 1,\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/exports'\npayload = {\n    \"format\": \"csv\",\n    \"filters\": [],\n    \"columns\": [\n        \"first_name\",\n        \"last_name\",\n        \"email\"\n    ],\n    \"location_id\": 1\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  '/api/exports/{id}':
    get:
      summary: 'Fetch an export'
      operationId: fetchAnExport
      description: "Returns the full export record including current `status` and (when ready)\na download URL."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      format:
                        type: string
                        examples:
                          - csv
                      status:
                        type: string
                        examples:
                          - pending
                      total_rows:
                        type: integer
                        examples:
                          - 0
                      file_name:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      filters:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      columns:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      error:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      started_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      finished_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      expires_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      download_url:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
      tags:
        - Exports
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/exports/8\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/exports/8\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/exports/8';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/exports/8'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    delete:
      summary: 'Delete an export'
      operationId: deleteAnExport
      description: "Deletes the export record and the underlying file from storage. Subsequent\ndownload attempts will return 404."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Export deleted.'
                examples:
                  -
                    message: 'Export deleted.'
      tags:
        - Exports
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request DELETE \\\n    \"https://klozzo.com/api/exports/8\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/exports/8\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"DELETE\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/exports/8';\n$response = $client->delete(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/exports/8'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('DELETE', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: id
        description: 'Export ID.'
        required: true
        schema:
          type: integer
          examples:
            - 8
  '/api/exports/{export_id}/download':
    get:
      summary: 'Download export file'
      operationId: downloadExportFile
      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— the signature is the credential — 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`."
      parameters: []
      responses:
        200:
          description: 'streamed file download'
          content:
            application/json:
              schema:
                type: string
                examples:
                  - '<binary CSV or XLSX>'
        403:
          description: 'expired or tampered signature'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Invalid signature.'
                examples:
                  -
                    message: 'Invalid signature.'
        404:
          description: 'not ready or pruned'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Not Found'
                examples:
                  -
                    message: 'Not Found'
      tags:
        - Exports
      security: []
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/exports/8/download\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/exports/8/download\"\n);\n\nconst headers = {\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/exports/8/download';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/exports/8/download'\nheaders = {\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: export_id
        description: 'Export ID.'
        required: true
        schema:
          type: integer
          examples:
            - 8
  /api/bulk-operations:
    post:
      summary: 'Start a bulk operation'
      operationId: startABulkOperation
      description: "Enqueues the job and returns 202 with the operation record. Poll\n`GET /api/bulk-operations/{id}` until `status=completed` or `failed`."
      parameters: []
      responses:
        202:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    examples:
                      - 31
                  action:
                    type: string
                    examples:
                      - tag
                  status:
                    type: string
                    examples:
                      - pending
                  total:
                    type: integer
                    examples:
                      - 3
                  processed:
                    type: integer
                    examples:
                      - 0
                  failed:
                    type: integer
                    examples:
                      - 0
                  progress:
                    type: integer
                    examples:
                      - 0
                  errors:
                    type:
                      - string
                      - 'null'
                    examples:
                      - null
                  started_at:
                    type:
                      - string
                      - 'null'
                    examples:
                      - null
                  finished_at:
                    type:
                      - string
                      - 'null'
                    examples:
                      - null
                  created_at:
                    type: string
                    examples:
                      - '2026-06-05T13:42:00+00:00'
                examples:
                  -
                    id: 31
                    action: tag
                    status: pending
                    total: 3
                    processed: 0
                    failed: 0
                    progress: 0
                    errors: null
                    started_at: null
                    finished_at: null
                    created_at: '2026-06-05T13:42:00+00:00'
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'An action that does not exist'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Action no es una opción válida.'
                      errors:
                        type: object
                        properties:
                          action:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Action no es una opción válida.'
                    examples:
                      -
                        message: 'Action no es una opción válida.'
                        errors:
                          action:
                            - 'Action no es una opción válida.'
                  -
                    description: 'No targets'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Falta payload.ids.'
                      errors:
                        type: object
                        properties:
                          payload.ids:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Falta payload.ids.'
                    examples:
                      -
                        message: 'Falta payload.ids.'
                        errors:
                          payload.ids:
                            - 'Falta payload.ids.'
      tags:
        - 'Bulk Operations'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: 'Action to run (`tag`, `untag`, `delete`, etc. — see `BulkOperation::ACTIONS`).'
                  examples:
                    - tag
                payload:
                  type: object
                  description: 'Action-specific payload. Must include `ids`.'
                  properties:
                    ids:
                      type: array
                      description: 'Target contact IDs (min 1).'
                      items:
                        type: integer
                      examples:
                        -
                          - 42
                          - 43
                          - 44
                    tag_id:
                      type:
                        - integer
                        - 'null'
                      description: 'Required for `tag`/`untag`.'
                      examples:
                        - 3
                  required:
                    - ids
                  examples:
                    - []
              required:
                - action
                - payload
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/bulk-operations\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"action\\\": \\\"tag\\\",\n    \\\"payload\\\": {\n        \\\"ids\\\": [\n            42,\n            43,\n            44\n        ],\n        \\\"tag_id\\\": 3\n    }\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/bulk-operations\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"action\": \"tag\",\n    \"payload\": {\n        \"ids\": [\n            42,\n            43,\n            44\n        ],\n        \"tag_id\": 3\n    }\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/bulk-operations';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'action' => 'tag',\n            'payload' => [\n                'ids' => [42, 43, 44],\n                'tag_id' => 3,\n            ],\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/bulk-operations'\npayload = {\n    \"action\": \"tag\",\n    \"payload\": {\n        \"ids\": [\n            42,\n            43,\n            44\n        ],\n        \"tag_id\": 3\n    }\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  '/api/bulk-operations/{bulkOperation_id}':
    get:
      summary: 'Bulk operation status'
      operationId: bulkOperationStatus
      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)."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    examples:
                      - 31
                  action:
                    type: string
                    examples:
                      - tag
                  status:
                    type: string
                    examples:
                      - processing
                  total:
                    type: integer
                    examples:
                      - 3
                  processed:
                    type: integer
                    examples:
                      - 2
                  failed:
                    type: integer
                    examples:
                      - 0
                  progress:
                    type: integer
                    examples:
                      - 66
                  errors:
                    type:
                      - string
                      - 'null'
                    examples:
                      - null
                  started_at:
                    type: string
                    examples:
                      - '2026-06-05T13:42:01+00:00'
                  finished_at:
                    type:
                      - string
                      - 'null'
                    examples:
                      - null
                  created_at:
                    type: string
                    examples:
                      - '2026-06-05T13:42:00+00:00'
                examples:
                  -
                    id: 31
                    action: tag
                    status: processing
                    total: 3
                    processed: 2
                    failed: 0
                    progress: 66
                    errors: null
                    started_at: '2026-06-05T13:42:01+00:00'
                    finished_at: null
                    created_at: '2026-06-05T13:42:00+00:00'
        404:
          description: 'Does not exist, or belongs to another location'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No query results for model.'
                examples:
                  -
                    message: 'No query results for model.'
      tags:
        - 'Bulk Operations'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/bulk-operations/31\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/bulk-operations/31\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/bulk-operations/31';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/bulk-operations/31'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: bulkOperation_id
        description: 'Bulk operation ID.'
        required: true
        schema:
          type: integer
          examples:
            - 31
  /api/v1/events:
    post:
      summary: 'Report events from a server'
      operationId: reportEventsFromAServer
      description: "Reports events your own server knows about — a purchase, a refund, a\nrenewal — 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."
      parameters: []
      responses:
        202:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  received:
                    type: integer
                    examples:
                      - 2
                  rejected:
                    type: integer
                    examples:
                      - 1
                  errors:
                    type: object
                    properties:
                      1:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - '`purchase` needs a `value`.'
                examples:
                  -
                    received: 2
                    rejected: 1
                    errors:
                      '1':
                        - '`purchase` needs a `value`.'
        401:
          description: 'No key, or a key that does not exist'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'A Bearer token with your site secret key is required.'
                examples:
                  -
                    message: 'A Bearer token with your site secret key is required.'
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'An empty batch'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Falta events.'
                      errors:
                        type: object
                        properties:
                          events:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Falta events.'
                    examples:
                      -
                        message: 'Falta events.'
                        errors:
                          events:
                            - 'Falta events.'
                  -
                    description: 'More than 500 events in one call'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Events no puede tener más de 500 elementos.'
                      errors:
                        type: object
                        properties:
                          events:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Events no puede tener más de 500 elementos.'
                    examples:
                      -
                        message: 'Events no puede tener más de 500 elementos.'
                        errors:
                          events:
                            - 'Events no puede tener más de 500 elementos.'
        429:
          description: "Over the site's budget"
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Too Many Attempts.'
                examples:
                  -
                    message: 'Too Many Attempts.'
      tags:
        - 'Pixel · server events'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                anonymous_id:
                  type:
                    - string
                    - 'null'
                  description: "The visitor's id, from the hidden `kz_anonymous_id` field your form received."
                  examples:
                    - 0d5b6b6e-3e1f-4a5e-9a0a-6c4b0e4b1a2c
                events:
                  type: array
                  description: 'The events to record.'
                  items:
                    type: object
                    properties:
                      event_id:
                        type: string
                        description: 'Your id for this event; the same value the browser used, if it also reported it.'
                        examples:
                          - ord_10293
                      action_source:
                        type: string
                        description: 'Always `server`.'
                        examples:
                          - server
                      name:
                        type: string
                        description: ''
                        examples:
                          - purchase
                      anonymous_id:
                        type:
                          - string
                          - 'null'
                        description: 'Must be a valid UUID.'
                        examples:
                          - 6b72fe4a-5b40-307c-bc24-f79acf9a1bb9
                      occurred_at:
                        type:
                          - string
                          - 'null'
                        description: 'When it happened. Within 7 days past and 5 minutes future.'
                        examples:
                          - '2026-08-02T18:04:00-06:00'
                      url:
                        type:
                          - string
                          - 'null'
                        description: 'The full URL where it happened.'
                        examples:
                          - 'https://example.com/checkout/gracias'
                      path:
                        type:
                          - string
                          - 'null'
                        description: 'The path alone, if you would rather not send the query string.'
                        examples:
                          - /checkout/gracias
                      value:
                        type:
                          - number
                          - 'null'
                        description: 'The amount, for monetary events.'
                        examples:
                          - 1899.5
                      currency:
                        type:
                          - string
                          - 'null'
                        description: 'ISO 4217.'
                        examples:
                          - MXN
                      properties:
                        type:
                          - object
                          - 'null'
                        description: 'Anything else about the event.'
                        properties: {  }
                        examples:
                          -
                            order_id: ORD-10293
                      traits:
                        type:
                          - object
                          - 'null'
                        description: 'Identity fields (`email`, `phone`, `first_name`, `last_name`, `company`).'
                        properties: {  }
                        examples:
                          -
                            email: ana@tienda.test
                    required:
                      - event_id
                      - action_source
                      - name
                  examples:
                    - []
              required:
                - events
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/v1/events\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"anonymous_id\\\": \\\"0d5b6b6e-3e1f-4a5e-9a0a-6c4b0e4b1a2c\\\",\n    \\\"events\\\": [\n        {\n            \\\"event_id\\\": \\\"ord_10293\\\",\n            \\\"action_source\\\": \\\"server\\\",\n            \\\"name\\\": \\\"purchase\\\",\n            \\\"anonymous_id\\\": \\\"6b72fe4a-5b40-307c-bc24-f79acf9a1bb9\\\",\n            \\\"occurred_at\\\": \\\"2026-08-02T18:04:00-06:00\\\",\n            \\\"url\\\": \\\"https:\\\\/\\\\/example.com\\\\/checkout\\\\/gracias\\\",\n            \\\"path\\\": \\\"\\\\/checkout\\\\/gracias\\\",\n            \\\"value\\\": 1899.5,\n            \\\"currency\\\": \\\"MXN\\\",\n            \\\"properties\\\": {\n                \\\"order_id\\\": \\\"ORD-10293\\\"\n            },\n            \\\"traits\\\": {\n                \\\"email\\\": \\\"ana@tienda.test\\\"\n            }\n        }\n    ]\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/v1/events\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"anonymous_id\": \"0d5b6b6e-3e1f-4a5e-9a0a-6c4b0e4b1a2c\",\n    \"events\": [\n        {\n            \"event_id\": \"ord_10293\",\n            \"action_source\": \"server\",\n            \"name\": \"purchase\",\n            \"anonymous_id\": \"6b72fe4a-5b40-307c-bc24-f79acf9a1bb9\",\n            \"occurred_at\": \"2026-08-02T18:04:00-06:00\",\n            \"url\": \"https:\\/\\/example.com\\/checkout\\/gracias\",\n            \"path\": \"\\/checkout\\/gracias\",\n            \"value\": 1899.5,\n            \"currency\": \"MXN\",\n            \"properties\": {\n                \"order_id\": \"ORD-10293\"\n            },\n            \"traits\": {\n                \"email\": \"ana@tienda.test\"\n            }\n        }\n    ]\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/v1/events';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'anonymous_id' => '0d5b6b6e-3e1f-4a5e-9a0a-6c4b0e4b1a2c',\n            'events' => [\n                [\n                    'event_id' => 'ord_10293',\n                    'action_source' => 'server',\n                    'name' => 'purchase',\n                    'anonymous_id' => '6b72fe4a-5b40-307c-bc24-f79acf9a1bb9',\n                    'occurred_at' => '2026-08-02T18:04:00-06:00',\n                    'url' => 'https://example.com/checkout/gracias',\n                    'path' => '/checkout/gracias',\n                    'value' => 1899.5,\n                    'currency' => 'MXN',\n                    'properties' => ['order_id' => 'ORD-10293'],\n                    'traits' => ['email' => 'ana@tienda.test'],\n                ],\n            ],\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/v1/events'\npayload = {\n    \"anonymous_id\": \"0d5b6b6e-3e1f-4a5e-9a0a-6c4b0e4b1a2c\",\n    \"events\": [\n        {\n            \"event_id\": \"ord_10293\",\n            \"action_source\": \"server\",\n            \"name\": \"purchase\",\n            \"anonymous_id\": \"6b72fe4a-5b40-307c-bc24-f79acf9a1bb9\",\n            \"occurred_at\": \"2026-08-02T18:04:00-06:00\",\n            \"url\": \"https:\\/\\/example.com\\/checkout\\/gracias\",\n            \"path\": \"\\/checkout\\/gracias\",\n            \"value\": 1899.5,\n            \"currency\": \"MXN\",\n            \"properties\": {\n                \"order_id\": \"ORD-10293\"\n            },\n            \"traits\": {\n                \"email\": \"ana@tienda.test\"\n            }\n        }\n    ]\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  /api/webhook-endpoints:
    get:
      summary: 'List webhook endpoints'
      operationId: listWebhookEndpoints
      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 — they are shown once, at creation."
      parameters:
        -
          in: query
          name: location_id
          description: 'Scope to a location.'
          required: false
          schema:
            type: integer
            description: 'Scope to a location.'
            examples:
              - 1
        -
          in: query
          name: is_active
          description: 'Filter active vs disabled.'
          required: false
          schema:
            type: boolean
            description: 'Filter active vs disabled.'
            examples:
              - true
        -
          in: query
          name: per_page
          description: 'Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
          required: false
          schema:
            type: integer
            description: 'Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
            examples:
              - 20
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        location_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        url:
                          type: string
                          examples:
                            - 'https://example.test/webhooks/9MTvekde'
                        events:
                          type: array
                          items:
                            type: string
                          examples:
                            -
                              - contact.created
                              - message.received
                        is_active:
                          type: boolean
                          examples:
                            - true
                        last_delivery_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        created_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        updated_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                    examples:
                      -
                        -
                          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:
                    type: object
                    properties:
                      first:
                        type: string
                        examples:
                          - '/?page=1'
                      last:
                        type: string
                        examples:
                          - '/?page=1'
                      prev:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      next:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        examples:
                          - 1
                      from:
                        type: integer
                        examples:
                          - 1
                      last_page:
                        type: integer
                        examples:
                          - 1
                      links:
                        type: array
                        items:
                          type: object
                          properties:
                            url:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            label:
                              type: string
                              examples:
                                - '&laquo; Previous'
                            page:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            active:
                              type: boolean
                              examples:
                                - false
                        examples:
                          -
                            -
                              url: null
                              label: '&laquo; Previous'
                              page: null
                              active: false
                            -
                              url: '/?page=1'
                              label: '1'
                              page: 1
                              active: true
                            -
                              url: null
                              label: 'Next &raquo;'
                              page: null
                              active: false
                      path:
                        type: string
                        examples:
                          - /
                      per_page:
                        type: integer
                        examples:
                          - 20
                      to:
                        type: integer
                        examples:
                          - 2
                      total:
                        type: integer
                        examples:
                          - 2
                examples:
                  -
                    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: '&laquo; Previous'
                          page: null
                          active: false
                        -
                          url: '/?page=1'
                          label: '1'
                          page: 1
                          active: true
                        -
                          url: null
                          label: 'Next &raquo;'
                          page: null
                          active: false
                      path: /
                      per_page: 20
                      to: 2
                      total: 2
      tags:
        - 'Webhook Endpoints (outbound)'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/webhook-endpoints?location_id=1&is_active=1&per_page=20\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/webhook-endpoints\"\n);\n\nconst params = {\n    \"location_id\": \"1\",\n    \"is_active\": \"1\",\n    \"per_page\": \"20\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/webhook-endpoints';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'location_id' => '1',\n            'is_active' => '1',\n            'per_page' => '20',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/webhook-endpoints'\nparams = {\n  'location_id': '1',\n  'is_active': '1',\n  'per_page': '20',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers, params=params)\nresponse.json()"
    post:
      summary: 'Register a webhook endpoint'
      operationId: registerAWebhookEndpoint
      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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      location_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      url:
                        type: string
                        examples:
                          - 'https://example.test/webhooks/tP7QtxDt'
                      events:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - contact.created
                            - message.received
                      is_active:
                        type: boolean
                        examples:
                          - true
                      last_delivery_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      secret:
                        type: string
                        examples:
                          - nHsIVY0AexDAbMktLudb8xsq6Ofw0OXkmU7NjPL1
                examples:
                  -
                    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
        422:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Not a URL'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Url no es una dirección web válida.'
                      errors:
                        type: object
                        properties:
                          url:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Url no es una dirección web válida.'
                    examples:
                      -
                        message: 'Url no es una dirección web válida.'
                        errors:
                          url:
                            - 'Url no es una dirección web válida.'
                  -
                    description: 'An event name that does not exist'
                    type: object
                    properties:
                      message:
                        type: string
                        examples:
                          - 'Events.0 no es una opción válida.'
                      errors:
                        type: object
                        properties:
                          events.0:
                            type: array
                            items:
                              type: string
                            examples:
                              -
                                - 'Events.0 no es una opción válida.'
                    examples:
                      -
                        message: 'Events.0 no es una opción válida.'
                        errors:
                          events.0:
                            - 'Events.0 no es una opción válida.'
      tags:
        - 'Webhook Endpoints (outbound)'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                location_id:
                  type:
                    - integer
                    - 'null'
                  description: 'Scope to a location.'
                  examples:
                    - 1
                url:
                  type: string
                  description: 'HTTPS URL that will receive POST deliveries (max 2048 chars).'
                  examples:
                    - 'https://hooks.example.com/herd'
                events:
                  type: array
                  description: 'Event names this endpoint subscribes to. At least one.'
                  items:
                    type: string
                  examples:
                    -
                      - contact.created
                      - contact.updated
                is_active:
                  type: boolean
                  description: 'Default true.'
                  examples:
                    - true
              required:
                - url
                - events
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/webhook-endpoints\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"location_id\\\": 1,\n    \\\"url\\\": \\\"https:\\\\/\\\\/hooks.example.com\\\\/herd\\\",\n    \\\"events\\\": [\n        \\\"contact.created\\\",\n        \\\"contact.updated\\\"\n    ],\n    \\\"is_active\\\": true\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/webhook-endpoints\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"location_id\": 1,\n    \"url\": \"https:\\/\\/hooks.example.com\\/herd\",\n    \"events\": [\n        \"contact.created\",\n        \"contact.updated\"\n    ],\n    \"is_active\": true\n};\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/webhook-endpoints';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'location_id' => 1,\n            'url' => 'https://hooks.example.com/herd',\n            'events' => ['contact.created', 'contact.updated'],\n            'is_active' => true,\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/webhook-endpoints'\npayload = {\n    \"location_id\": 1,\n    \"url\": \"https:\\/\\/hooks.example.com\\/herd\",\n    \"events\": [\n        \"contact.created\",\n        \"contact.updated\"\n    ],\n    \"is_active\": true\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers, json=payload)\nresponse.json()"
  '/api/webhook-endpoints/{webhookEndpoint_id}':
    get:
      summary: 'Fetch a webhook endpoint'
      operationId: fetchAWebhookEndpoint
      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** — 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`."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      location_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      url:
                        type: string
                        examples:
                          - 'https://example.test/webhooks/Mh00hWJg'
                      events:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - contact.created
                            - message.received
                      is_active:
                        type: boolean
                        examples:
                          - true
                      last_delivery_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
        404:
          description: 'Does not exist, or belongs to another location'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'No query results for model.'
                examples:
                  -
                    message: 'No query results for model.'
      tags:
        - 'Webhook Endpoints (outbound)'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/webhook-endpoints/6\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/webhook-endpoints/6\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/webhook-endpoints/6';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/webhook-endpoints/6'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
    patch:
      summary: 'Update a webhook endpoint'
      operationId: updateAWebhookEndpoint
      description: "Updates a webhook endpoint by id, changing only the fields you send. To\nrotate the signing secret, delete and recreate."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      location_id:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      url:
                        type: string
                        examples:
                          - 'https://example.test/webhooks/USS1QLNW'
                      events:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - contact.created
                            - message.received
                      is_active:
                        type: boolean
                        examples:
                          - true
                      last_delivery_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      created_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      updated_at:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                examples:
                  -
                    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
      tags:
        - 'Webhook Endpoints (outbound)'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: 'HTTPS URL (max 2048 chars).'
                  examples:
                    - 'https://hooks.example.com/herd'
                events:
                  type: array
                  description: 'Subscribed event names.'
                  items:
                    type: string
                  examples:
                    -
                      - architecto
                is_active:
                  type: boolean
                  description: 'Pause without deleting.'
                  examples:
                    - false
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request PATCH \\\n    \"https://klozzo.com/api/webhook-endpoints/6\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"url\\\": \\\"https:\\\\/\\\\/hooks.example.com\\\\/herd\\\",\n    \\\"events\\\": [\n        \\\"architecto\\\"\n    ],\n    \\\"is_active\\\": false\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/webhook-endpoints/6\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"url\": \"https:\\/\\/hooks.example.com\\/herd\",\n    \"events\": [\n        \"architecto\"\n    ],\n    \"is_active\": false\n};\n\nfetch(url, {\n    method: \"PATCH\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/webhook-endpoints/6';\n$response = $client->patch(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'url' => 'https://hooks.example.com/herd',\n            'events' => ['architecto'],\n            'is_active' => false,\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/webhook-endpoints/6'\npayload = {\n    \"url\": \"https:\\/\\/hooks.example.com\\/herd\",\n    \"events\": [\n        \"architecto\"\n    ],\n    \"is_active\": false\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('PATCH', url, headers=headers, json=payload)\nresponse.json()"
    delete:
      summary: 'Delete a webhook endpoint'
      operationId: deleteAWebhookEndpoint
      description: "Removes the endpoint and invalidates its signing secret. Historical\n`WebhookDelivery` records remain for audit."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Webhook endpoint deleted.'
                examples:
                  -
                    message: 'Webhook endpoint deleted.'
      tags:
        - 'Webhook Endpoints (outbound)'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request DELETE \\\n    \"https://klozzo.com/api/webhook-endpoints/6\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/webhook-endpoints/6\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"DELETE\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/webhook-endpoints/6';\n$response = $client->delete(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/webhook-endpoints/6'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('DELETE', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: webhookEndpoint_id
        description: 'Endpoint ID.'
        required: true
        schema:
          type: integer
          examples:
            - 6
  '/api/webhook-endpoints/{webhookEndpoint_id}/deliveries':
    get:
      summary: 'List delivery attempts for an endpoint'
      operationId: listDeliveryAttemptsForAnEndpoint
      description: "Returns recent delivery attempts (one row per HTTP call, including retries),\nnewest first. Useful for debugging non-2xx responses from your endpoint."
      parameters:
        -
          in: query
          name: per_page
          description: 'Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
          required: false
          schema:
            type: integer
            description: 'Rows per page. Default 20, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
            examples:
              - 20
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        endpoint_id:
                          type: integer
                          examples:
                            - 229
                        event_type:
                          type: string
                          examples:
                            - contact.created
                        response_status:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        attempts:
                          type: integer
                          examples:
                            - 0
                        delivered_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        created_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                    examples:
                      -
                        -
                          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:
                    type: object
                    properties:
                      first:
                        type: string
                        examples:
                          - '/?page=1'
                      last:
                        type: string
                        examples:
                          - '/?page=1'
                      prev:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      next:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        examples:
                          - 1
                      from:
                        type: integer
                        examples:
                          - 1
                      last_page:
                        type: integer
                        examples:
                          - 1
                      links:
                        type: array
                        items:
                          type: object
                          properties:
                            url:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            label:
                              type: string
                              examples:
                                - '&laquo; Previous'
                            page:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            active:
                              type: boolean
                              examples:
                                - false
                        examples:
                          -
                            -
                              url: null
                              label: '&laquo; Previous'
                              page: null
                              active: false
                            -
                              url: '/?page=1'
                              label: '1'
                              page: 1
                              active: true
                            -
                              url: null
                              label: 'Next &raquo;'
                              page: null
                              active: false
                      path:
                        type: string
                        examples:
                          - /
                      per_page:
                        type: integer
                        examples:
                          - 20
                      to:
                        type: integer
                        examples:
                          - 2
                      total:
                        type: integer
                        examples:
                          - 2
                examples:
                  -
                    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: '&laquo; Previous'
                          page: null
                          active: false
                        -
                          url: '/?page=1'
                          label: '1'
                          page: 1
                          active: true
                        -
                          url: null
                          label: 'Next &raquo;'
                          page: null
                          active: false
                      path: /
                      per_page: 20
                      to: 2
                      total: 2
      tags:
        - 'Webhook Endpoints (outbound)'
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/webhook-endpoints/6/deliveries?per_page=20\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/webhook-endpoints/6/deliveries\"\n);\n\nconst params = {\n    \"per_page\": \"20\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/webhook-endpoints/6/deliveries';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'per_page' => '20',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/webhook-endpoints/6/deliveries'\nparams = {\n  'per_page': '20',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers, params=params)\nresponse.json()"
    parameters:
      -
        in: path
        name: webhookEndpoint_id
        description: 'Endpoint ID.'
        required: true
        schema:
          type: integer
          examples:
            - 6
  /api/notifications:
    get:
      summary: 'List notifications'
      operationId: listNotifications
      description: "Lists the notifications of the user the token belongs to, newest first.\nPass `unread=true` to restrict to unread items."
      parameters:
        -
          in: query
          name: unread
          description: 'Only return unread notifications.'
          required: false
          schema:
            type: boolean
            description: 'Only return unread notifications.'
            examples:
              - true
        -
          in: query
          name: per_page
          description: 'Rows per page. Default 25, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
          required: false
          schema:
            type: integer
            description: 'Rows per page. Default 25, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).'
            examples:
              - 25
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          examples:
                            - 9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234
                        type:
                          type: string
                          examples:
                            - App\Notifications\NewMessageReceived
                        data:
                          type: object
                          properties:
                            conversation_id:
                              type: integer
                              examples:
                                - 17
                            preview:
                              type: string
                              examples:
                                - 'Hi Ada!'
                        read_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        created_at:
                          type: string
                          examples:
                            - '2026-06-05T13:42:00+00:00'
                    examples:
                      -
                        -
                          id: 9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234
                          type: App\Notifications\NewMessageReceived
                          data:
                            conversation_id: 17
                            preview: 'Hi Ada!'
                          read_at: null
                          created_at: '2026-06-05T13:42:00+00:00'
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        examples:
                          - 1
                      last_page:
                        type: integer
                        examples:
                          - 4
                      per_page:
                        type: integer
                        examples:
                          - 25
                      total:
                        type: integer
                        examples:
                          - 87
                      unread_count:
                        type: integer
                        examples:
                          - 12
                examples:
                  -
                    data:
                      -
                        id: 9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234
                        type: App\Notifications\NewMessageReceived
                        data:
                          conversation_id: 17
                          preview: 'Hi Ada!'
                        read_at: null
                        created_at: '2026-06-05T13:42:00+00:00'
                    meta:
                      current_page: 1
                      last_page: 4
                      per_page: 25
                      total: 87
                      unread_count: 12
      tags:
        - Notifications
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/notifications?unread=1&per_page=25\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/notifications\"\n);\n\nconst params = {\n    \"unread\": \"1\",\n    \"per_page\": \"25\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/notifications';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'unread' => '1',\n            'per_page' => '25',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/notifications'\nparams = {\n  'unread': '1',\n  'per_page': '25',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers, params=params)\nresponse.json()"
  /api/notifications/unread-count:
    get:
      summary: 'Unread count'
      operationId: unreadCount
      description: "Returns how many notifications you have unread, as a single integer — a\nlightweight endpoint for badge polling."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  unread_count:
                    type: integer
                    examples:
                      - 12
                examples:
                  -
                    unread_count: 12
      tags:
        - Notifications
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/api/notifications/unread-count\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/notifications/unread-count\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/notifications/unread-count';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/notifications/unread-count'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers)\nresponse.json()"
  '/api/notifications/{id}/read':
    post:
      summary: 'Mark a notification as read'
      operationId: markANotificationAsRead
      description: "Marks one notification as read. Idempotent: marking an already-read\nnotification is a no-op (returns the\nexisting read_at)."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        examples:
                          - 9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234
                      type:
                        type: string
                        examples:
                          - App\Notifications\NewMessageReceived
                      data:
                        type: object
                        properties:
                          conversation_id:
                            type: integer
                            examples:
                              - 17
                          preview:
                            type: string
                            examples:
                              - 'Hi Ada!'
                      read_at:
                        type: string
                        examples:
                          - '2026-06-05T13:43:00+00:00'
                      created_at:
                        type: string
                        examples:
                          - '2026-06-05T13:42:00+00:00'
                  unread_count:
                    type: integer
                    examples:
                      - 11
                examples:
                  -
                    data:
                      id: 9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234
                      type: App\Notifications\NewMessageReceived
                      data:
                        conversation_id: 17
                        preview: 'Hi Ada!'
                      read_at: '2026-06-05T13:43:00+00:00'
                      created_at: '2026-06-05T13:42:00+00:00'
                    unread_count: 11
        404:
          description: 'Not yours, or the UUID does not exist'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Not Found'
                examples:
                  -
                    message: 'Not Found'
      tags:
        - Notifications
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/notifications/9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234/read\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/notifications/9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234/read\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/notifications/9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234/read';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/notifications/9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234/read'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers)\nresponse.json()"
    parameters:
      -
        in: path
        name: id
        description: 'Notification UUID.'
        required: true
        schema:
          type: string
          examples:
            - 9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234
  /api/notifications/read-all:
    post:
      summary: 'Mark all notifications as read'
      operationId: markAllNotificationsAsRead
      description: "Marks every notification of the user the token belongs to as read, in one\ncall. It affects **your** notifications only — the\nones belonging to the user the token was issued for — 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."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  unread_count:
                    type: integer
                    examples:
                      - 0
                examples:
                  -
                    unread_count: 0
      tags:
        - Notifications
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request POST \\\n    \"https://klozzo.com/api/notifications/read-all\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/notifications/read-all\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\n\nfetch(url, {\n    method: \"POST\",\n    headers,\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/notifications/read-all';\n$response = $client->post(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/notifications/read-all'\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('POST', url, headers=headers)\nresponse.json()"
  /api/notifications/preferences:
    put:
      summary: 'Update notification preferences'
      operationId: updateNotificationPreferences
      description: "Updates your notification preferences. Currently only the `muted` list is\nsupported — notifications whose `type`\nmatches an entry in the list are skipped at delivery time. Provide the\nfull desired list (full-replace, not append)."
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      muted:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - App\Notifications\NewMessageReceived
                examples:
                  -
                    data:
                      muted:
                        - App\Notifications\NewMessageReceived
        422:
          description: 'Not a list'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Muted debe ser una lista.'
                  errors:
                    type: object
                    properties:
                      muted:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - 'Muted debe ser una lista.'
                examples:
                  -
                    message: 'Muted debe ser una lista.'
                    errors:
                      muted:
                        - 'Muted debe ser una lista.'
      tags:
        - Notifications
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                muted:
                  type: array
                  description: 'Notification types to mute.'
                  items:
                    type: string
                  examples:
                    -
                      - App\Notifications\NewMessageReceived
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request PUT \\\n    \"https://klozzo.com/api/notifications/preferences\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"muted\\\": [\n        \\\"App\\\\\\\\Notifications\\\\\\\\NewMessageReceived\\\"\n    ]\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/notifications/preferences\"\n);\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"muted\": [\n        \"App\\\\Notifications\\\\NewMessageReceived\"\n    ]\n};\n\nfetch(url, {\n    method: \"PUT\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/notifications/preferences';\n$response = $client->put(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'json' => [\n            'muted' => ['App\\\\Notifications\\\\NewMessageReceived'],\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/notifications/preferences'\npayload = {\n    \"muted\": [\n        \"App\\\\Notifications\\\\NewMessageReceived\"\n    ]\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('PUT', url, headers=headers, json=payload)\nresponse.json()"
  /api/audit-logs:
    get:
      summary: 'List audit log entries'
      operationId: listAuditLogEntries
      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 — including `viewer`.\nThe log exists to settle an argument between two people, and a record only\none of them can open settles nothing."
      parameters:
        -
          in: query
          name: subject_type
          description: 'Eloquent class FQN of the audited model.'
          required: false
          schema:
            type: string
            description: 'Eloquent class FQN of the audited model.'
            examples:
              - App\Models\Contact
        -
          in: query
          name: subject_id
          description: 'Audited record ID.'
          required: false
          schema:
            type: integer
            description: 'Audited record ID.'
            examples:
              - 42
        -
          in: query
          name: user_id
          description: 'Filter by actor.'
          required: false
          schema:
            type: integer
            description: 'Filter by actor.'
            examples:
              - 7
        -
          in: query
          name: action
          description: 'One of `created`, `updated`, `deleted`, `bulk_deleted`, `owner_changed`.'
          required: false
          schema:
            type: string
            description: 'One of `created`, `updated`, `deleted`, `bulk_deleted`, `owner_changed`.'
            examples:
              - updated
        -
          in: query
          name: from
          description: 'date Lower bound on `created_at` (inclusive, ISO-8601).'
          required: false
          schema:
            type: string
            description: 'date Lower bound on `created_at` (inclusive, ISO-8601).'
            examples:
              - '2026-06-01'
        -
          in: query
          name: to
          description: 'date Upper bound on `created_at` (inclusive, ISO-8601).'
          required: false
          schema:
            type: string
            description: 'date Upper bound on `created_at` (inclusive, ISO-8601).'
            examples:
              - '2026-06-05'
        -
          in: query
          name: per_page
          description: 'Rows per page. Default 50, maximum 200. See [Lists, paging and filters](#lists-paging-and-filters).'
          required: false
          schema:
            type: integer
            description: 'Rows per page. Default 50, maximum 200. See [Lists, paging and filters](#lists-paging-and-filters).'
            examples:
              - 50
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        user_id:
                          type: integer
                          examples:
                            - 3783
                        location_id:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        action:
                          type: string
                          examples:
                            - deleted
                        subject_type:
                          type: string
                          examples:
                            - App\Models\Contact
                        subject_id:
                          type: integer
                          examples:
                            - 23891
                        old_values:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                        new_values:
                          type: object
                          properties:
                            first_name:
                              type: string
                              examples:
                                - Rowan
                        ip_address:
                          type: string
                          examples:
                            - 197.119.215.250
                        user_agent:
                          type: string
                          examples:
                            - 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/5340 (KHTML, like Gecko) Chrome/40.0.882.0 Mobile Safari/5340'
                        created_at:
                          type:
                            - string
                            - 'null'
                          examples:
                            - null
                    examples:
                      -
                        -
                          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:
                    type: object
                    properties:
                      first:
                        type: string
                        examples:
                          - '/?page=1'
                      last:
                        type: string
                        examples:
                          - '/?page=1'
                      prev:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                      next:
                        type:
                          - string
                          - 'null'
                        examples:
                          - null
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        examples:
                          - 1
                      from:
                        type: integer
                        examples:
                          - 1
                      last_page:
                        type: integer
                        examples:
                          - 1
                      links:
                        type: array
                        items:
                          type: object
                          properties:
                            url:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            label:
                              type: string
                              examples:
                                - '&laquo; Previous'
                            page:
                              type:
                                - string
                                - 'null'
                              examples:
                                - null
                            active:
                              type: boolean
                              examples:
                                - false
                        examples:
                          -
                            -
                              url: null
                              label: '&laquo; Previous'
                              page: null
                              active: false
                            -
                              url: '/?page=1'
                              label: '1'
                              page: 1
                              active: true
                            -
                              url: null
                              label: 'Next &raquo;'
                              page: null
                              active: false
                      path:
                        type: string
                        examples:
                          - /
                      per_page:
                        type: integer
                        examples:
                          - 50
                      to:
                        type: integer
                        examples:
                          - 2
                      total:
                        type: integer
                        examples:
                          - 2
                examples:
                  -
                    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: '&laquo; Previous'
                          page: null
                          active: false
                        -
                          url: '/?page=1'
                          label: '1'
                          page: 1
                          active: true
                        -
                          url: null
                          label: 'Next &raquo;'
                          page: null
                          active: false
                      path: /
                      per_page: 50
                      to: 2
                      total: 2
        403:
          description: 'A token with no location resolved'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'This action is unauthorized.'
                examples:
                  -
                    message: 'This action is unauthorized.'
        422:
          description: 'A page size above the ceiling'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - 'Per page no puede ser mayor que 200.'
                  errors:
                    type: object
                    properties:
                      per_page:
                        type: array
                        items:
                          type: string
                        examples:
                          -
                            - 'Per page no puede ser mayor que 200.'
                examples:
                  -
                    message: 'Per page no puede ser mayor que 200.'
                    errors:
                      per_page:
                        - 'Per page no puede ser mayor que 200.'
      tags:
        - 'Audit Log'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                subject_type:
                  type:
                    - string
                    - 'null'
                  description: 'Must not be greater than 255 characters.'
                  examples:
                    - b
                subject_id:
                  type:
                    - integer
                    - 'null'
                  description: ''
                  examples:
                    - 16
                user_id:
                  type:
                    - integer
                    - 'null'
                  description: ''
                  examples:
                    - 16
                action:
                  type:
                    - string
                    - 'null'
                  description: 'Must not be greater than 50 characters.'
                  examples:
                    - 'n'
                from:
                  type:
                    - string
                    - 'null'
                  description: 'Must be a valid date.'
                  examples:
                    - '2026-08-26T02:19:50'
                to:
                  type:
                    - string
                    - 'null'
                  description: 'Must be a valid date.'
                  examples:
                    - '2026-08-26T02:19:50'
                per_page:
                  type:
                    - integer
                    - 'null'
                  description: 'Must be at least 1. Must not be greater than 200.'
                  examples:
                    - 7
      x-codeSamples:
        -
          lang: bash
          label: cURL
          source: "curl --request GET \\\n    --get \"https://klozzo.com/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\" \\\n    --header \"Authorization: Bearer {YOUR_API_TOKEN}\" \\\n    --header \"Content-Type: application/json\" \\\n    --header \"Accept: application/json\" \\\n    --data \"{\n    \\\"subject_type\\\": \\\"b\\\",\n    \\\"subject_id\\\": 16,\n    \\\"user_id\\\": 16,\n    \\\"action\\\": \\\"n\\\",\n    \\\"from\\\": \\\"2026-08-26T02:19:50\\\",\n    \\\"to\\\": \\\"2026-08-26T02:19:50\\\",\n    \\\"per_page\\\": 7\n}\""
        -
          lang: javascript
          label: JavaScript
          source: "const url = new URL(\n    \"https://klozzo.com/api/audit-logs\"\n);\n\nconst params = {\n    \"subject_type\": \"App\\Models\\Contact\",\n    \"subject_id\": \"42\",\n    \"user_id\": \"7\",\n    \"action\": \"updated\",\n    \"from\": \"2026-06-01\",\n    \"to\": \"2026-06-05\",\n    \"per_page\": \"50\",\n};\nObject.keys(params)\n    .forEach(key => url.searchParams.append(key, params[key]));\n\nconst headers = {\n    \"Authorization\": \"Bearer {YOUR_API_TOKEN}\",\n    \"Content-Type\": \"application/json\",\n    \"Accept\": \"application/json\",\n};\n\nlet body = {\n    \"subject_type\": \"b\",\n    \"subject_id\": 16,\n    \"user_id\": 16,\n    \"action\": \"n\",\n    \"from\": \"2026-08-26T02:19:50\",\n    \"to\": \"2026-08-26T02:19:50\",\n    \"per_page\": 7\n};\n\nfetch(url, {\n    method: \"GET\",\n    headers,\n    body: JSON.stringify(body),\n}).then(response => response.json());"
        -
          lang: php
          label: PHP
          source: "$client = new \\GuzzleHttp\\Client();\n$url = 'https://klozzo.com/api/audit-logs';\n$response = $client->get(\n    $url,\n    [\n        'headers' => [\n            'Authorization' => 'Bearer {YOUR_API_TOKEN}',\n            'Content-Type' => 'application/json',\n            'Accept' => 'application/json',\n        ],\n        'query' => [\n            'subject_type' => 'App\\Models\\Contact',\n            'subject_id' => '42',\n            'user_id' => '7',\n            'action' => 'updated',\n            'from' => '2026-06-01',\n            'to' => '2026-06-05',\n            'per_page' => '50',\n        ],\n        'json' => [\n            'subject_type' => 'b',\n            'subject_id' => 16,\n            'user_id' => 16,\n            'action' => 'n',\n            'from' => '2026-08-26T02:19:50',\n            'to' => '2026-08-26T02:19:50',\n            'per_page' => 7,\n        ],\n    ]\n);\n$body = $response->getBody();\nprint_r(json_decode((string) $body));"
        -
          lang: python
          label: Python
          source: "import requests\nimport json\n\nurl = 'https://klozzo.com/api/audit-logs'\npayload = {\n    \"subject_type\": \"b\",\n    \"subject_id\": 16,\n    \"user_id\": 16,\n    \"action\": \"n\",\n    \"from\": \"2026-08-26T02:19:50\",\n    \"to\": \"2026-08-26T02:19:50\",\n    \"per_page\": 7\n}\nparams = {\n  'subject_type': 'App\\Models\\Contact',\n  'subject_id': '42',\n  'user_id': '7',\n  'action': 'updated',\n  'from': '2026-06-01',\n  'to': '2026-06-05',\n  'per_page': '50',\n}\nheaders = {\n  'Authorization': 'Bearer {YOUR_API_TOKEN}',\n  'Content-Type': 'application/json',\n  'Accept': 'application/json'\n}\n\nresponse = requests.request('GET', url, headers=headers, json=payload, params=params)\nresponse.json()"
