@letsbot/sdk 0.2.0 → 0.5.0

package/openapi/openapi.yaml

@@ -73,6 +73,8 @@ tags:
   description: Connection (instance) status, presence and settings.
 - name: Products
   description: Catalog products, collections and orders.
+- name: Orders
+  description: Record orders from your own store system (not Salla / Zid) to start the order journey and send the invoice.
 - name: Session
   description: QR linking and session state (QR-linked channels).
 - name: Archive
@@ -82,7 +84,7 @@ tags:
     authenticated with `X-Zapier-Api-Key`. Its operations carry their own `servers` and `security`.'
 - name: CRM
   description: 'The public CRM API at https://{workspace}.letsbot.net/api/v1/crm — contacts, companies, deals, tasks, activities,
-    quotes, products and REST-hook webhooks. Workspace API key (`X-Zapier-Api-Key`) with the `crm` scope ticked; the key acts
+    quotes, products, custom objects and REST-hook webhooks. Workspace API key (`X-Zapier-Api-Key`) with the `crm` scope ticked; the key acts
     for the whole workspace. Envelope `{success, data, meta?}` / `{success: false, error, code, errors?}`; 120 requests per
     minute per key.'
 paths:
@@ -4850,6 +4852,192 @@ paths:
           $ref: '#/components/responses/InternalError'
         '503':
           $ref: '#/components/responses/LifecycleUnavailable'
+  /orders:
+    post:
+      operationId: recordOrder
+      tags:
+      - Orders
+      summary: Record an order (order journey + invoice)
+      description: |-
+        For merchants whose orders live in their own system (not Salla / Zid). Each recorded order starts the order journey: every active automation reminder on «Order placed» (/panel/v2/automation-reminders) goes to this customer N days after `ordered_at` (rating request, discount, marketing…). When the request carries `invoice_url` (https page) or `invoice_pdf_url` (https PDF) the invoice is sent at once, once per order, through the invoices templates (/panel/v2/invoices).
+
+        Recording an order sends nothing by itself, so this is not a send endpoint. A customer who never wrote to the business is reached only on an official (Cloud API) number; `journey.reachable` tells you before the first reminder is due.
+
+        Validation failures always answer HTTP 422 `{"Status": false, "Message": ..., "errors": {...}}`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                order_id:
+                  type: string
+                  maxLength: 64
+                  pattern: ^[A-Za-z0-9._\-]+$
+                  description: Your order id. Used again by the cancel endpoint.
+                  examples:
+                  - ORD-1042
+                phone:
+                  $ref: '#/components/schemas/Phone'
+                customer_name:
+                  type: string
+                  maxLength: 191
+                ordered_at:
+                  type: string
+                  format: date-time
+                  description: Within the last 365 days and not in the future. Defaults to now.
+                total:
+                  type: number
+                  minimum: 0
+                currency:
+                  type: string
+                  maxLength: 8
+                  examples:
+                  - SAR
+                order_url:
+                  type: string
+                  format: uri
+                  maxLength: 2048
+                  description: https only.
+                store_name:
+                  type: string
+                  maxLength: 191
+                language:
+                  type: string
+                  enum:
+                  - ar
+                  - en
+                  - es
+                  - pt
+                invoice_number:
+                  type: string
+                  maxLength: 64
+                invoice_url:
+                  type: string
+                  format: uri
+                  maxLength: 2048
+                  description: https invoice page; sends the invoice at once.
+                invoice_pdf_url:
+                  type: string
+                  format: uri
+                  maxLength: 2048
+                  description: https invoice PDF; sends the invoice at once.
+                products:
+                  type: array
+                  maxItems: 20
+                  items:
+                    type: object
+                    properties:
+                      name:
+                        type: string
+                        maxLength: 191
+                      url:
+                        type: string
+                        format: uri
+                        maxLength: 2048
+                    required:
+                    - name
+              required:
+              - order_id
+              - phone
+      responses:
+        '201':
+          description: Order recorded.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  Status:
+                    type: boolean
+                  Message:
+                    type: string
+                  order_id:
+                    type: string
+                  journey:
+                    type: object
+                    properties:
+                      recorded:
+                        type: boolean
+                      ordered_at:
+                        type: string
+                        format: date-time
+                      reachable:
+                        type: boolean
+                        description: false = this customer never wrote to you and your number is QR-linked, so journey messages will not reach them.
+                  invoice:
+                    type: string
+                    enum:
+                    - not_requested
+                    - sent
+                    - skipped
+                    - failed
+                    - duplicate
+                    - 'off'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: No workspace is linked to this API key.
+        '409':
+          description: The workspace is still being prepared. Try again in a few minutes.
+        '422':
+          description: 'Validation failed (`{"Status": false, "Message": ..., "errors": {...}}`), or the phone is not a full international number, or `ordered_at` is out of range.'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          description: The order could not be recorded. Try again.
+        '503':
+          $ref: '#/components/responses/LifecycleUnavailable'
+  /orders/{orderId}/cancel:
+    post:
+      operationId: cancelOrder
+      tags:
+      - Orders
+      summary: Stop the order journey for a cancelled or refunded order
+      description: No further journey messages are sent for this order. Send the customer phone used when the order was recorded.
+      parameters:
+      - name: orderId
+        in: path
+        required: true
+        schema:
+          type: string
+          pattern: ^[A-Za-z0-9._\-]{1,64}$
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                phone:
+                  $ref: '#/components/schemas/Phone'
+              required:
+              - phone
+      responses:
+        '200':
+          description: OK. `cancelled` is false when no open order matches this id and phone.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  Status:
+                    type: boolean
+                  Message:
+                    type: string
+                  cancelled:
+                    type: boolean
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          description: No workspace is linked to this API key.
+        '422':
+          description: The phone is missing or not a full international number.
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '503':
+          $ref: '#/components/responses/LifecycleUnavailable'
   /product:
     post:
       operationId: getProducts
@@ -10693,10 +10881,21 @@ paths:
       tags:
         - CRM
       summary: Create a contact
-      description: "Creates a contact (WhatsApp customer) by phone. A phone that already exists answers 409 with that contact
-        in `data`. Scope: `crm`."
+      description: "Creates a contact (WhatsApp customer) by phone. A phone that already exists answers 409 `already_exists`
+        with that contact in `data`. A likely duplicate (the same number in another format, the same WhatsApp username or
+        the same e-mail) answers 409 `possible_duplicate` with `existing_id` and `duplicates` — update that contact, or
+        repeat with `?allow_duplicate=1` to create a new one anyway. Scope: `crm`."
       security:
         - zapierApiKey: []
+      parameters:
+        - name: allow_duplicate
+          in: query
+          required: false
+          description: "`1` / `true`: create the record even when a likely duplicate exists (otherwise 409
+            `possible_duplicate`)."
+          schema:
+            type: boolean
+            default: false
       requestBody:
         required: true
         content:
@@ -11060,9 +11259,20 @@ paths:
       tags:
         - CRM
       summary: Create a company
-      description: "Creates a company (account). Scope: `crm`."
+      description: "Creates a company (account). A likely duplicate (the same domain, or the same name once legal forms
+        are ignored) answers 409 `possible_duplicate` with `existing_id` and `duplicates`; repeat with
+        `?allow_duplicate=1` to create it anyway. Scope: `crm`."
       security:
         - zapierApiKey: []
+      parameters:
+        - name: allow_duplicate
+          in: query
+          required: false
+          description: "`1` / `true`: create the record even when a likely duplicate exists (otherwise 409
+            `possible_duplicate`)."
+          schema:
+            type: boolean
+            default: false
       requestBody:
         required: true
         content:
@@ -11145,6 +11355,8 @@ paths:
           $ref: "#/components/responses/CrmForbidden"
         "404":
           $ref: "#/components/responses/CrmNotFound"
+        "409":
+          $ref: "#/components/responses/CrmConflict"
         "422": *a1
         "429":
           $ref: "#/components/responses/TooManyRequests"
@@ -13309,16 +13521,21 @@ paths:
           $ref: "#/components/responses/CrmNotFound"
         "429":
           $ref: "#/components/responses/TooManyRequests"
-  /v1/crm/hooks:
+  /v1/crm/objects:
     x-letsbot-surface: zapier
-    servers: *a2
+    servers:
+      - url: https://{workspace}.letsbot.net/api
+        description: The workspace's own subdomain. The CRM API lives under /v1/crm.
+        variables:
+          workspace:
+            default: your-workspace
+            description: The workspace subdomain.
     get:
-      operationId: crmListHooks
+      operationId: crmListCustomObjects
       tags:
         - CRM
-      summary: List API webhook subscriptions
-      description: "Subscriptions created through the API (panel-made ones are managed in the panel). Secrets are never
-        returned again. Scope: `crm`."
+      summary: List custom objects
+      description: "The workspace's custom CRM objects (for example Projects or Properties) with their fields: key, label, type, options and whether a field is required or read-only (formula, rollup). Available while the workspace uses custom objects (CRM → Custom objects); until then these paths answer `404`. Scope: `crm`."
       security:
         - zapierApiKey: []
       responses:
@@ -13337,7 +13554,7 @@ paths:
                   data:
                     type: array
                     items:
-                      $ref: "#/components/schemas/CrmWebhookSubscription"
+                      $ref: "#/components/schemas/CrmCustomObject"
         "401":
           $ref: "#/components/responses/ZapierUnauthorized"
         "403":
@@ -13346,51 +13563,34 @@ paths:
           $ref: "#/components/responses/CrmNotFound"
         "429":
           $ref: "#/components/responses/TooManyRequests"
-    post:
-      operationId: crmSubscribeHook
+  /v1/crm/objects/{key}/schema:
+    x-letsbot-surface: zapier
+    servers:
+      - url: https://{workspace}.letsbot.net/api
+        description: The workspace's own subdomain. The CRM API lives under /v1/crm.
+        variables:
+          workspace:
+            default: your-workspace
+            description: The workspace subdomain.
+    get:
+      operationId: crmCustomObjectSchema
       tags:
         - CRM
-      summary: Subscribe a webhook (REST hook)
-      description: 'Zapier / Make / n8n REST-hook subscribe. Accepts `target_url` or `url`, and `event` or `events`. The
-        answer carries the signing `secret` ONCE. Deliveries are POSTed as CrmWebhookEvent with `X-LetsBot-Signature:
-        t=<unix>,v1=<hex HMAC-SHA256 of "t.body">`, `X-LetsBot-Event` and `X-LetsBot-Delivery`; failed deliveries are
-        retried with backoff (1 min, 5 min, 30 min, 2 h, 6 h); after 5 deliveries in a row fail the subscription is
-        switched off, and an HTTP 410 answer switches it off at once. Scope: `crm`.'
+      summary: Custom object fields, filters and sorts
+      description: "The object (as in the list) plus the lists-engine catalogue of its records: every field with its type, whether it can be filtered or sorted, and the filter operators. Scope: `crm`."
       security:
         - zapierApiKey: []
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                target_url:
-                  type: string
-                  format: uri
-                url:
-                  type: string
-                  format: uri
-                event:
-                  $ref: "#/components/schemas/CrmWebhookEventName"
-                events:
-                  type: array
-                  items:
-                    $ref: "#/components/schemas/CrmWebhookEventName"
-                source:
-                  type: string
-                  enum:
-                    - zapier
-                    - make
-                    - n8n
-                    - api
-                description:
-                  type:
-                    - string
-                    - "null"
+      parameters:
+        - name: key
+          in: path
+          required: true
+          description: The custom object key, e.g. `co_projects` (GET /v1/crm/objects).
+          schema:
+            type: string
+            pattern: ^co_[a-z][a-z0-9_]{1,12}$
       responses:
-        "201":
-          description: Subscribed.
+        "200":
+          description: OK
           content:
             application/json:
               schema:
@@ -13403,76 +13603,580 @@ paths:
                     const: true
                   data:
                     allOf:
-                      - $ref: "#/components/schemas/CrmWebhookSubscription"
                       - type: object
-                        required:
-                          - secret
+                        description: The object (as in GET /v1/crm/objects, without its `fields`).
                         properties:
-                          secret:
+                          key:
+                            type: string
+                          label_singular:
+                            type: object
+                            additionalProperties:
+                              type: string
+                          label_plural:
+                            type: object
+                            additionalProperties:
+                              type: string
+                          primary_field:
                             type: string
+                      - $ref: "#/components/schemas/CrmListSchema"
         "401":
           $ref: "#/components/responses/ZapierUnauthorized"
         "403":
           $ref: "#/components/responses/CrmForbidden"
         "404":
           $ref: "#/components/responses/CrmNotFound"
-        "422": *a1
         "429":
           $ref: "#/components/responses/TooManyRequests"
-  /v1/crm/hooks/events:
+  /v1/crm/objects/{key}/records:
     x-letsbot-surface: zapier
-    servers: *a2
+    servers:
+      - url: https://{workspace}.letsbot.net/api
+        description: The workspace's own subdomain. The CRM API lives under /v1/crm.
+        variables:
+          workspace:
+            default: your-workspace
+            description: The workspace subdomain.
     get:
-      operationId: crmListHookEvents
+      operationId: crmListCustomRecords
       tags:
         - CRM
-      summary: List webhook events
-      description: "The event catalogue. Scope: `crm`."
+      summary: List custom records
+      description: "Records of one custom object through the CRM lists engine: search, filters, saved views, sort and pages. Scope: `crm`."
       security:
         - zapierApiKey: []
-      responses:
-        "200":
-          description: OK
-          content:
-            application/json:
-              schema:
-                type: object
-                required:
-                  - success
-                  - data
-                properties:
-                  success:
-                    const: true
-                  data:
-                    type: array
-                    items:
-                      type: object
-                      required:
-                        - event
-                        - object
-                      properties:
-                        event:
-                          $ref: "#/components/schemas/CrmWebhookEventName"
-                        object:
-                          type: string
-        "401":
-          $ref: "#/components/responses/ZapierUnauthorized"
-        "403":
-          $ref: "#/components/responses/CrmForbidden"
-        "404":
-          $ref: "#/components/responses/CrmNotFound"
-        "429":
-          $ref: "#/components/responses/TooManyRequests"
-  /v1/crm/hooks/sample:
-    x-letsbot-surface: zapier
-    servers: *a2
-    get:
-      operationId: crmHookSample
-      tags:
-        - CRM
-      summary: Sample webhook payload
-      description: "One sample event built from the newest record of that object (empty when there is none) — for trigger
-        setup screens. Scope: `crm`."
+      parameters:
+        - name: key
+          in: path
+          required: true
+          description: The custom object key, e.g. `co_projects` (GET /v1/crm/objects).
+          schema:
+            type: string
+            pattern: ^co_[a-z][a-z0-9_]{1,12}$
+        - name: q
+          in: query
+          required: false
+          description: Free-text search.
+          schema:
+            type: string
+            maxLength: 100
+        - name: filters
+          in: query
+          required: false
+          description: 'Lists-engine filter, JSON: `{"match":"and|or","conditions":[{"field":"cf:status","op":"in","value":["active"]}]}`. GET
+            …/schema lists the fields and operators.'
+          schema:
+            type: string
+        - name: view
+          in: query
+          required: false
+          description: A saved view id (its filters / sort apply), or `all`.
+          schema:
+            type: string
+        - name: sort
+          in: query
+          required: false
+          description: Sort key (see …/schema `sorts`), e.g. `cf:budget`.
+          schema:
+            type: string
+        - name: dir
+          in: query
+          required: false
+          description: Sort direction.
+          schema:
+            type: string
+            enum:
+              - asc
+              - desc
+        - name: page
+          in: query
+          required: false
+          description: Page number.
+          schema:
+            type: integer
+            minimum: 1
+            default: 1
+        - name: per_page
+          in: query
+          required: false
+          description: Rows per page (max 100).
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 25
+        - name: updated_since
+          in: query
+          required: false
+          description: Only records changed at or after this ISO 8601 time (polling triggers).
+          schema:
+            type: string
+            format: date-time
+      responses:
+        "200":
+          description: One page.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    const: true
+                  data:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/CrmCustomRecord"
+                  meta:
+                    $ref: "#/components/schemas/CrmListMeta"
+        "401":
+          $ref: "#/components/responses/ZapierUnauthorized"
+        "403":
+          $ref: "#/components/responses/CrmForbidden"
+        "404":
+          $ref: "#/components/responses/CrmNotFound"
+        "422":
+          $ref: "#/components/responses/CrmValidationFailed"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+    post:
+      operationId: crmCreateCustomRecord
+      tags:
+        - CRM
+      summary: Create a custom record
+      description: "Creates a record. `values` is keyed by field key; the title field and required fields must be filled; formula and rollup fields are computed. Relation fields take a record id (a list of ids when the field allows many). Validated like the panel; fires the record created automations. Scope: `crm`."
+      security:
+        - zapierApiKey: []
+      parameters:
+        - name: key
+          in: path
+          required: true
+          description: The custom object key, e.g. `co_projects` (GET /v1/crm/objects).
+          schema:
+            type: string
+            pattern: ^co_[a-z][a-z0-9_]{1,12}$
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CrmCustomRecordInput"
+      responses:
+        "201":
+          description: Created.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    const: true
+                  data:
+                    $ref: "#/components/schemas/CrmCustomRecord"
+        "401":
+          $ref: "#/components/responses/ZapierUnauthorized"
+        "403":
+          $ref: "#/components/responses/CrmForbidden"
+        "404":
+          $ref: "#/components/responses/CrmNotFound"
+        "422":
+          $ref: "#/components/responses/CrmValidationFailed"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+  /v1/crm/objects/{key}/records/search:
+    x-letsbot-surface: zapier
+    servers:
+      - url: https://{workspace}.letsbot.net/api
+        description: The workspace's own subdomain. The CRM API lives under /v1/crm.
+        variables:
+          workspace:
+            default: your-workspace
+            description: The workspace subdomain.
+    get:
+      operationId: crmSearchCustomRecords
+      tags:
+        - CRM
+      summary: Find custom records
+      description: "Records whose title (or a sortable text field) contains `q`, most recently updated first. Scope: `crm`."
+      security:
+        - zapierApiKey: []
+      parameters:
+        - name: key
+          in: path
+          required: true
+          description: The custom object key, e.g. `co_projects` (GET /v1/crm/objects).
+          schema:
+            type: string
+            pattern: ^co_[a-z][a-z0-9_]{1,12}$
+        - name: q
+          in: query
+          required: false
+          description: Text to find.
+          schema:
+            type: string
+            maxLength: 100
+        - name: per_page
+          in: query
+          required: false
+          description: Maximum records (max 100).
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 25
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    const: true
+                  data:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/CrmCustomRecord"
+        "401":
+          $ref: "#/components/responses/ZapierUnauthorized"
+        "403":
+          $ref: "#/components/responses/CrmForbidden"
+        "404":
+          $ref: "#/components/responses/CrmNotFound"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+  /v1/crm/objects/{key}/records/{id}:
+    x-letsbot-surface: zapier
+    servers:
+      - url: https://{workspace}.letsbot.net/api
+        description: The workspace's own subdomain. The CRM API lives under /v1/crm.
+        variables:
+          workspace:
+            default: your-workspace
+            description: The workspace subdomain.
+    get:
+      operationId: crmGetCustomRecord
+      tags:
+        - CRM
+      summary: Get a custom record
+      description: "One record with its field values. Scope: `crm`."
+      security:
+        - zapierApiKey: []
+      parameters:
+        - name: key
+          in: path
+          required: true
+          description: The custom object key, e.g. `co_projects` (GET /v1/crm/objects).
+          schema:
+            type: string
+            pattern: ^co_[a-z][a-z0-9_]{1,12}$
+        - name: id
+          in: path
+          required: true
+          description: The record id.
+          schema:
+            type: integer
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    const: true
+                  data:
+                    $ref: "#/components/schemas/CrmCustomRecord"
+        "401":
+          $ref: "#/components/responses/ZapierUnauthorized"
+        "403":
+          $ref: "#/components/responses/CrmForbidden"
+        "404":
+          $ref: "#/components/responses/CrmNotFound"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+    patch:
+      operationId: crmUpdateCustomRecord
+      tags:
+        - CRM
+      summary: Update a custom record
+      description: "Only the values sent change (send `null` to clear one). Changes are kept in the field history with source `api` and fire the record updated automations. Scope: `crm`."
+      security:
+        - zapierApiKey: []
+      parameters:
+        - name: key
+          in: path
+          required: true
+          description: The custom object key, e.g. `co_projects` (GET /v1/crm/objects).
+          schema:
+            type: string
+            pattern: ^co_[a-z][a-z0-9_]{1,12}$
+        - name: id
+          in: path
+          required: true
+          description: The record id.
+          schema:
+            type: integer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CrmCustomRecordInput"
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    const: true
+                  data:
+                    $ref: "#/components/schemas/CrmCustomRecord"
+        "401":
+          $ref: "#/components/responses/ZapierUnauthorized"
+        "403":
+          $ref: "#/components/responses/CrmForbidden"
+        "404":
+          $ref: "#/components/responses/CrmNotFound"
+        "422":
+          $ref: "#/components/responses/CrmValidationFailed"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+    delete:
+      operationId: crmDeleteCustomRecord
+      tags:
+        - CRM
+      summary: Delete a custom record
+      description: "Moves the record to the trash. Scope: `crm`."
+      security:
+        - zapierApiKey: []
+      parameters:
+        - name: key
+          in: path
+          required: true
+          description: The custom object key, e.g. `co_projects` (GET /v1/crm/objects).
+          schema:
+            type: string
+            pattern: ^co_[a-z][a-z0-9_]{1,12}$
+        - name: id
+          in: path
+          required: true
+          description: The record id.
+          schema:
+            type: integer
+      responses:
+        "200":
+          description: Deleted.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    const: true
+                  data:
+                    type: object
+                    required:
+                      - id
+                      - deleted
+                    properties:
+                      id:
+                        type: integer
+                      deleted:
+                        const: true
+        "401":
+          $ref: "#/components/responses/ZapierUnauthorized"
+        "403":
+          $ref: "#/components/responses/CrmForbidden"
+        "404":
+          $ref: "#/components/responses/CrmNotFound"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+  /v1/crm/hooks:
+    x-letsbot-surface: zapier
+    servers: *a2
+    get:
+      operationId: crmListHooks
+      tags:
+        - CRM
+      summary: List API webhook subscriptions
+      description: "Subscriptions created through the API (panel-made ones are managed in the panel). Secrets are never
+        returned again. Scope: `crm`."
+      security:
+        - zapierApiKey: []
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    const: true
+                  data:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/CrmWebhookSubscription"
+        "401":
+          $ref: "#/components/responses/ZapierUnauthorized"
+        "403":
+          $ref: "#/components/responses/CrmForbidden"
+        "404":
+          $ref: "#/components/responses/CrmNotFound"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+    post:
+      operationId: crmSubscribeHook
+      tags:
+        - CRM
+      summary: Subscribe a webhook (REST hook)
+      description: 'Zapier / Make / n8n REST-hook subscribe. Accepts `target_url` or `url`, and `event` or `events`. The
+        answer carries the signing `secret` ONCE. Deliveries are POSTed as CrmWebhookEvent with `X-LetsBot-Signature:
+        t=<unix>,v1=<hex HMAC-SHA256 of "t.body">`, `X-LetsBot-Event` and `X-LetsBot-Delivery`; failed deliveries are
+        retried with backoff (1 min, 5 min, 30 min, 2 h, 6 h); after 5 deliveries in a row fail the subscription is
+        switched off, and an HTTP 410 answer switches it off at once. Scope: `crm`.'
+      security:
+        - zapierApiKey: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                target_url:
+                  type: string
+                  format: uri
+                url:
+                  type: string
+                  format: uri
+                event:
+                  $ref: "#/components/schemas/CrmWebhookEventName"
+                events:
+                  type: array
+                  items:
+                    $ref: "#/components/schemas/CrmWebhookEventName"
+                source:
+                  type: string
+                  enum:
+                    - zapier
+                    - make
+                    - n8n
+                    - api
+                description:
+                  type:
+                    - string
+                    - "null"
+      responses:
+        "201":
+          description: Subscribed.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    const: true
+                  data:
+                    allOf:
+                      - $ref: "#/components/schemas/CrmWebhookSubscription"
+                      - type: object
+                        required:
+                          - secret
+                        properties:
+                          secret:
+                            type: string
+        "401":
+          $ref: "#/components/responses/ZapierUnauthorized"
+        "403":
+          $ref: "#/components/responses/CrmForbidden"
+        "404":
+          $ref: "#/components/responses/CrmNotFound"
+        "422": *a1
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+  /v1/crm/hooks/events:
+    x-letsbot-surface: zapier
+    servers: *a2
+    get:
+      operationId: crmListHookEvents
+      tags:
+        - CRM
+      summary: List webhook events
+      description: "The event catalogue. Scope: `crm`."
+      security:
+        - zapierApiKey: []
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - success
+                  - data
+                properties:
+                  success:
+                    const: true
+                  data:
+                    type: array
+                    items:
+                      type: object
+                      required:
+                        - event
+                        - object
+                      properties:
+                        event:
+                          $ref: "#/components/schemas/CrmWebhookEventName"
+                        object:
+                          type: string
+        "401":
+          $ref: "#/components/responses/ZapierUnauthorized"
+        "403":
+          $ref: "#/components/responses/CrmForbidden"
+        "404":
+          $ref: "#/components/responses/CrmNotFound"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
+  /v1/crm/hooks/sample:
+    x-letsbot-surface: zapier
+    servers: *a2
+    get:
+      operationId: crmHookSample
+      tags:
+        - CRM
+      summary: Sample webhook payload
+      description: "One sample event built from the newest record of that object (empty when there is none) — for trigger
+        setup screens. Scope: `crm`."
       security:
         - zapierApiKey: []
       parameters:
@@ -13909,6 +14613,23 @@ components:
           type:
           - string
           - 'null'
+        whatsapp_bsuid:
+          type:
+          - string
+          - 'null'
+          description: Meta's business-scoped user ID for a customer who hides their number behind a WhatsApp username
+            (e.g. `EG.2288384708632117`). Not a phone number. Sent only for workspaces with WhatsApp username support
+            switched on.
+        whatsapp_username:
+          type:
+          - string
+          - 'null'
+          description: The customer's WhatsApp @username, without the `@`. Display only. Sent only for workspaces with
+            WhatsApp username support switched on.
+        phone_available:
+          type: boolean
+          description: '`false` when the customer keeps their number private: `phone` then holds an identity, so do not
+            SMS, call or store it as a number. Sent only for workspaces with WhatsApp username support switched on.'
         labels:
           type: array
           items:
@@ -14733,6 +15454,7 @@ components:
             - missing_scope
             - validation_failed
             - already_exists
+            - possible_duplicate
             - conflict
             - forbidden
             - unprocessable
@@ -14745,6 +15467,27 @@ components:
               type: string
         data:
           description: "On `already_exists`: the existing record."
+        existing_id:
+          type: integer
+          description: "On `already_exists` / `possible_duplicate`: the id of the record to update instead."
+        duplicates:
+          type: array
+          description: "On `possible_duplicate`: the likely duplicates, best match first. Repeat the request with
+            `?allow_duplicate=1` to create the record anyway."
+          items:
+            type: object
+            required:
+              - id
+              - reason
+            properties:
+              id:
+                type: integer
+              reason:
+                type: string
+                description: "What matched: `phone`, `bsuid`, `email` (contacts) or `domain`, `company_name` (companies)."
+              confidence:
+                type: integer
+                description: 0–100.
     CrmContact:
       type: object
       required:
@@ -14805,6 +15548,23 @@ components:
         updated_at: *a2
         url:
           type: string
+        whatsapp_bsuid:
+          type:
+            - string
+            - "null"
+          description: Meta's business-scoped user ID for a customer who hides their number behind a WhatsApp username
+            (e.g. `EG.2288384708632117`). Not a phone number. Sent only for workspaces with WhatsApp username support
+            switched on.
+        whatsapp_username:
+          type:
+            - string
+            - "null"
+          description: The customer's WhatsApp @username, without the `@`. Display only. Sent only for workspaces with
+            WhatsApp username support switched on.
+        phone_available:
+          type: boolean
+          description: "`false` when the customer keeps their number private: `phone` then holds an identity, so do not
+            SMS, call or store it as a number. Sent only for workspaces with WhatsApp username support switched on."
     CrmCompany:
       type: object
       required:
@@ -15210,6 +15970,134 @@ components:
         updated_at: *a2
         url:
           type: string
+    CrmCustomObject:
+      type: object
+      description: A merchant-defined CRM object (custom objects).
+      required:
+        - key
+        - label_singular
+        - label_plural
+        - primary_field
+        - fields
+      properties:
+        key:
+          type: string
+          description: Immutable object key, `co_<slug>`.
+          examples:
+            - co_projects
+        label_singular:
+          type: object
+          description: Names by language (`ar`, `en`).
+          additionalProperties:
+            type: string
+        label_plural:
+          type: object
+          additionalProperties:
+            type: string
+        primary_field:
+          type: string
+          description: Key of the field used as the record title.
+        fields:
+          type: array
+          items:
+            type: object
+            required:
+              - key
+              - label
+              - type
+              - required
+              - read_only
+            properties:
+              key:
+                type: string
+              label:
+                type: string
+              type:
+                type: string
+                enum:
+                  - text
+                  - textarea
+                  - number
+                  - currency
+                  - date
+                  - datetime
+                  - select
+                  - multiselect
+                  - boolean
+                  - url
+                  - email
+                  - phone
+                  - user
+                  - relation
+                  - formula
+                  - rollup
+                  - file
+              required:
+                type: boolean
+              read_only:
+                type: boolean
+                description: Formula and rollup fields are computed by LetsBot.
+              options:
+                type:
+                  - array
+                  - "null"
+                description: Choices of a `select` / `multiselect` field (send the `value`).
+                items:
+                  type: object
+                  properties:
+                    value:
+                      type: string
+                    label:
+                      type: string
+              settings:
+                type: object
+                additionalProperties: true
+                description: "Type settings, e.g. `{target: company, many: true}` for a relation, `{currency: SAR}` for a currency."
+    CrmCustomRecord:
+      type: object
+      required:
+        - id
+        - object
+        - title
+        - values
+      properties:
+        id:
+          type: integer
+        object:
+          type: string
+          description: The object key.
+        title:
+          type:
+            - string
+            - "null"
+          description: The title field's value.
+        owner_user_id:
+          type:
+            - integer
+            - "null"
+        values:
+          type: object
+          additionalProperties: true
+          description: Field key → value.
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    CrmCustomRecordInput:
+      type: object
+      properties:
+        values:
+          type: object
+          additionalProperties: true
+          description: Field key → value. Dropdowns take the option value, dates YYYY-MM-DD, relation fields a record id (a
+            list of ids when the field allows many), user fields a team member id, file fields uploaded file ids.
+        owner_user_id:
+          type:
+            - integer
+            - "null"
+          description: Team member who owns the record.
     CrmProduct:
       type: object
       required:
@@ -15269,6 +16157,12 @@ components:
         - quote.sent
         - quote.viewed
         - quote.accepted
+        - quote.signed
+        - quote.paid
+        - invoice.created
+        - form.submitted
+        - deal.assigned
+        - health.at_risk
     CrmWebhookSubscription:
       type: object
       required:
@@ -15360,6 +16254,105 @@ components:
               type:
                 - string
                 - "null"
+        invoice:
+          type: object
+          description: "invoice.created only (`data` is the quote): the invoice made from the quote."
+          properties:
+            id:
+              type: integer
+            kind:
+              type: string
+              enum:
+                - erp
+                - simplified
+            number:
+              type:
+                - string
+                - "null"
+            erp_invoice_id:
+              type:
+                - integer
+                - "null"
+            currency:
+              type: string
+            subtotal:
+              type: string
+            discount_total:
+              type: string
+            tax_total:
+              type: string
+            total:
+              type: string
+            issue_date:
+              type:
+                - string
+                - "null"
+              format: date
+            uuid:
+              type: string
+        form:
+          type: object
+          description: "form.submitted only (`data` is the contact): which form and what was answered."
+          properties:
+            source:
+              type: string
+              enum:
+                - web_form
+                - typeform
+                - google_forms
+            form_id:
+              type:
+                - integer
+                - "null"
+            form_name:
+              type:
+                - string
+                - "null"
+            submission_id:
+              type:
+                - integer
+                - "null"
+            deal_id:
+              type:
+                - integer
+                - "null"
+            contact_created:
+              type: boolean
+            answers:
+              type: array
+              items:
+                type: object
+                properties:
+                  label:
+                    type: string
+                  value:
+                    type: string
+        assignment:
+          type: object
+          description: "deal.assigned only: the new owner and the one before (null for a new deal)."
+          properties:
+            owner_user_id:
+              type: integer
+            previous_owner_user_id:
+              type:
+                - integer
+                - "null"
+        health:
+          type: object
+          description: "health.at_risk only (`object` is contact or company): the health score and why."
+          properties:
+            score:
+              type:
+                - integer
+                - "null"
+            previous:
+              type:
+                - string
+                - "null"
+            reasons:
+              type: array
+              items:
+                type: string
   responses:
     LegacyValidationFailure:
       description: 'Validation failed (historic contract, the default: HTTP 202, nothing was done). With
@@ -15515,7 +16508,8 @@ components:
           schema:
             $ref: "#/components/schemas/CrmError"
     CrmConflict:
-      description: Conflict (`already_exists` with the existing record in `data`, or `conflict`).
+      description: "Conflict: `already_exists` (the existing record in `data`), `possible_duplicate` (a likely duplicate
+        — `existing_id` + `duplicates`; repeat with `?allow_duplicate=1` to create anyway) or `conflict`."
       content:
         application/json:
           schema: