Conduyt Calls API

openapi: 3.2.0
info:
  title: Conduyt Calls API
  version: 1.0.0
  description: 'The Conduyt CRM API provides programmatic access to your CRM data including

    contacts, companies, deals, pipelines, tasks, notes, automations, invoices,

    email sequences, and more.


    ## Authentication


    All authenticated endpoints require a Bearer token (API key) in the

    `Authorization` header:


    ```

    Authorization: Bearer cdy_

    ```


    API keys are generated in **Settings > API Keys** within the Conduyt

    dashboard. Keys use the `cdy_` prefix and are hashed with bcrypt on

    creation — the full key is shown exactly once at creation time.


    Session cookie authentication (`conduyt_session`) is also supported for

    browser-based clients but is not recommended for integrations.


    ## Rate Limiting


    API keys enforce a per-key rate limit. New keys default to 100 requests per

    minute and can be configured at creation time or with PATCH `/api-keys/{id}`.

    Some public and provider-facing endpoints also enforce stricter per-IP or

    per-account limits. When exceeded, the API returns `429 Too Many Requests`

    with a `Retry-After` header indicating seconds until the next allowed

    request.


    | Endpoint Group | Limit |

    |---------------------|---------------------|

    | API keys | Default 100 / min per key |

    | Login/reset | 5 / min per IP |

    | Registration | 3 / hour per IP |

    | Contact/Deal create | 30 / min per IP |

    | Inbound messages | 120 / min per account/IP |


    ## Pagination


    List endpoints support cursor-based pagination via query parameters:


    - `page` — Page number (default: 1)

    - `per_page` — Items per page (default: 50, max: 200)

    - `limit` — Accepted as an alias of `per_page` on `GET /contacts`; if both are

    sent they must carry the same value.


    A page size above the maximum, a non-integer, a value below 1, or a

    pagination key repeated with different values is rejected with `400`

    (the message names the parameter and the rule); nothing is silently

    clamped or ignored.


    Responses include a `meta` object: `{ page, per_page, total }`.


    An operation that documents its own pagination rules follows those instead.

    `GET /sms-providers/options` pages with an opaque `cursor` and a `limit`

    that is capped at 50 rather than rejected; its responses carry

    `meta: { nextCursor, truncated }`.


    ## Response Format


    All successful responses wrap data in a `data` envelope:

    ```json

    { "data": { ... } }

    ```


    Error responses use:

    ```json

    { "error": "Human-readable error message" }

    ```


    ## Multi-Tenancy


    Conduyt is multi-tenant. All data is scoped to the authenticated user''s

    current account. API keys are bound to a specific account at creation time.


    ## Webhook Events


    Outbound webhooks fire on events including:

    `contact.created`, `contact.updated`, `contact.deleted`,

    `deal.created`, `deal.updated`, `deal.won`, `deal.lost`,

    `task.created`, `task.completed`, `note.created`,

    `appointment.created`, `appointment.updated`,

    `form.submitted`, `invoice.paid`


    Payloads are signed with HMAC-SHA256 using the webhook''s secret. Retry

    schedule: 1m, 5m, 30m, 2h, 12h, 72h (7 total attempts including the initial delivery).'
  contact:
    name: Conduyt Support
    url: https://conduyt.app
    email: support@conduyt.app
  license:
    name: Proprietary
    url: https://conduyt.app/terms
servers:
- url: https://conduyt.app/api/v1
  description: Production
security:
- BearerAuth: []
tags:
- name: Calls
  description: Call log management
paths:
  /calls:
    get:
      operationId: listCalls
      summary: List call records
      tags:
      - Calls
      parameters:
      - name: contact_id
        in: query
        required: false
        description: Query parameter read by this route.
        schema:
          type: string
      - name: date_from
        in: query
        required: false
        description: Query parameter read by this route.
        schema:
          type: string
      - name: date_to
        in: query
        required: false
        description: Query parameter read by this route.
        schema:
          type: string
      - name: direction
        in: query
        required: false
        description: Query parameter read by this route.
        schema:
          type: string
      - name: minimal
        in: query
        required: false
        description: Query parameter read by this route.
        schema:
          type: boolean
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
          default: 1
          minimum: 1
        x-default-provenance: handler_literal
      - name: per_page
        in: query
        required: false
        description: Items per page (max 200)
        schema:
          type: integer
          default: 50
          minimum: 1
          maximum: 200
        x-default-provenance: handler_literal
      - name: status
        in: query
        required: false
        description: Query parameter read by this route.
        schema:
          type: string
      - name: user_id
        in: query
        required: false
        description: Query parameter read by this route.
        schema:
          type: string
      responses:
        '200':
          description: Paginated calls
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      data: {}
                      meta: {}
                    required:
                    - data
                    - meta
                required:
                - data
    post:
      operationId: createCallRecord
      summary: Create a call record
      tags:
      - Calls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - direction
              - fromNumber
              - toNumber
              properties:
                direction:
                  type: string
                  enum:
                  - inbound
                  - outbound
                fromNumber:
                  type: string
                toNumber:
                  type: string
                contactId:
                  type: string
                  format: uuid
                duration:
                  type: integer
                notes:
                  type: string
                disposition:
                  description: Read by the handler from the JSON body (the route declares no schema for its type).
                source:
                  description: Read by the handler from the JSON body (the route declares no schema for its type).
                status:
                  description: Read by the handler from the JSON body (the route declares no schema for its type).
      responses:
        '201':
          description: Call record created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataEnvelope'
      parameters: []
  /calls/{id}:
    get:
      operationId: getCall
      summary: Get a call by ID
      tags:
      - Calls
      parameters:
      - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Call details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      contact: {}
                      hasRecording: {}
                      hasVoicemail: {}
                      recordings:
                        type: array
                        description: Every recording of the call (#419), in the order they were recorded; [] when hasRecording is false.
                        items:
                          $ref: '#/components/schemas/DialerCallRecording'
                    required:
                    - contact
                    - hasRecording
                    - hasVoicemail
                    - recordings
                required:
                - data
    patch:
      operationId: updateCall
      summary: Update a call record (e.g., add notes)
      tags:
      - Calls
      parameters:
      - $ref: '#/components/parameters/IdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                notes:
                  type: string
                duration:
                  type: integer
                endedAt:
                  description: Read by the handler from the JSON body (the route declares no schema for its type).
                status:
                  description: Read by the handler from the JSON body (the route declares no schema for its type).
      responses:
        '200':
          description: Call updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      hasRecording: {}
                      hasVoicemail: {}
                    required:
                    - hasRecording
                    - hasVoicemail
                required:
                - data
  /calls/{id}/link:
    post:
      operationId: linkCallToContact
      summary: Link a contact-less call to a contact (optionally attaching the call's number)
      description: 'Board #35, the unknown-caller prompt''s "Search a contact". Links the call to the contact with a compare-and-set on the locked call row: an unlinked call is linked; a call already linked to THIS contact answers 200 with `alreadyLinked: true` (idempotent); a call linked to another contact is 409 `call_already_linked`, or 404 `call_not_found` when that contact is hidden from the caller. With `attachNumber: true` the call''s number (the caller on an inbound call, stored under the account''s country) is written into the contact''s next free phone slot (the empty primary phone, then phone_2, phone_3 ... the account''s numbered phone fields); nothing is ever overwritten, a number the contact already has writes nothing (`alreadyOnContact: true`), every slot taken is 409 `no_free_phone_slot`, and a number another live contact has as its primary phone is 409 `number_on_another_contact` (checked for every attach, serialized per number). A contact erased by a GDPR forget (or being erased) is 409 `contact_forgotten`. With `dryRun: true` the same checks run and the answer says what the request would do, writing nothing. Nothing is written on any refusal. Requires `dialer.create`, plus `contacts.edit` when `attachNumber` is true; the contact must be one the caller may see (404 otherwise) and, for an attach, edit (403 `contact_not_editable` for a collaborator), re-proven under the row lock. API keys need the `calls` scope (a `dialer` key covers it) and the `contacts` scope. A new link records an `unknown_call_linked` activity on the contact and the call''s touch.'
      tags:
      - Calls
      parameters:
      - $ref: '#/components/parameters/IdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - contactId
              properties:
                contactId:
                  type: string
                  format: uuid
                attachNumber:
                  type: boolean
                  default: false
                  description: Also write the call's number into the contact's next free phone slot.
                dryRun:
                  type: boolean
                  default: false
                  description: Run every check and answer what the request would do (attached.slot, alreadyOnContact, alreadyLinked, or the same refusal); nothing is written.
            examples:
              attach:
                summary: Attach the caller's number to an existing contact and link the call
                value:
                  contactId: 3f8a0c4e-1111-4222-8333-444455556666
                  attachNumber: true
              linkOnly:
                summary: Link the call without touching the contact's phones
                value:
                  contactId: 3f8a0c4e-1111-4222-8333-444455556666
              preview:
                summary: Ask what an attach would do, writing nothing
                value:
                  contactId: 3f8a0c4e-1111-4222-8333-444455556666
                  attachNumber: true
                  dryRun: true
      responses:
        '200':
          description: Linked (or already linked to this contact)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      contact: {}
                    required:
                    - contact
                required:
                - data
              examples:
                attachedAsSecondPhone:
                  value:
                    data:
                      callId: 9b2d7c1a-5e4f-4a3b-9c8d-7e6f5a4b3c2d
                      contactId: 3f8a0c4e-1111-4222-8333-444455556666
                      alreadyLinked: false
                      attached:
                        number: '+15095550142'
                        slot: phone_2
                        alreadyOnContact: false
                      dryRun: false
                      contact:
                        id: 3f8a0c4e-1111-4222-8333-444455556666
                        name: Maria Ruiz
        '400':
          description: Malformed body (`invalid_json`, `invalid_body`, `unknown_field`, `contact_id_invalid`, `attach_number_invalid`, `dry_run_invalid`)
        '403':
          description: Missing `dialer.create`, or `contacts.edit` for an attach, or `contact_not_editable` (the caller may see the contact but not edit it)
        '404':
          description: The call (`call_not_found`) or the contact (`contact_not_found`) does not exist in this account or is not visible
        '409':
          description: '`call_already_linked`, `no_free_phone_slot`, `number_on_another_contact`, `number_owner_undecidable` (too many contacts share the number''s last seven digits to prove who owns it; link without attachNumber), or `contact_forgotten` (the contact was erased by a GDPR forget, or is being erased); nothing was written'
        '422':
          description: '`number_unusable`: the call has no usable phone number to attach'
  /calls/unknown-callers:
    get:
      operationId: countUnknownCallers
      summary: Count a line's unknown callers since an instant (the toll-free quick mode…
      description: 'Board #35. `total`: inbound calls to that line since `since` that arrived with no contact (the ones still contact-less plus the ones the unknown-caller prompt linked since); `unmatched`: those still contact-less (list them with GET /dialer/history?unmatched=1&line=...). `since` is the caller''s start of day and must be within the last 31 days. Requires `dialer.view`; counts only, under the Call history visibility rule (a scoped member counts their own calls, contact-less calls and calls linked to a contact they can see).'
      tags:
      - Calls
      parameters:
      - name: line
        in: query
        required: true
        description: Our line (the number the callers dialed), any formatting.
        schema:
          type: string
        example: '+18005550199'
      - name: since
        in: query
        required: true
        description: ISO instant (the caller's midnight).
        schema:
          type: string
          format: date-time
        example: 2026-10-15 07:00:00+00:00
      responses:
        '200':
          description: The counts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      line: {}
                      since: {}
                      total: {}
                      unmatched: {}
                    required:
                    - line
                    - since
                    - total
                    - unmatched
                required:
                - data
              examples:
                today:
                  value:
                    data:
                      line: '+18005550199'
                      since: 2026-10-15 07:00:00+00:00
                      total: 14
                      unmatched: 9
        '400':
          description: '`line_required`, `line_conflict`, `line_invalid`, `since_required`, `since_conflict` or `since_out_of_range`'
  /calls/voice-drop:
    post:
      x-generated: true
      operationId: postCallsVoiceDrop
      summary: Create / invoke calls voice-drop
      tags:
      - Calls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - contactId
              properties:
                contactId:
                  type: string
                  format: uuid
                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                recording:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Leading and trailing whitespace is trimmed before the length check, so a blank value is refused.
                fromNumber:
                  type: string
                  pattern: ^\+[1-9]\d{6,14}$
                onHuman:
                  type: string
                  enum:
                  - hang_up
                  - play
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      callId: {}
                      providerId: {}
                      contactId: {}
                      fromNumber: {}
                      toNumber: {}
                      recording: {}
                      onHuman: {}
                      status:
                        type: string
                    required:
                    - callId
                    - providerId
                    - contactId
                    - fromNumber
                    - toNumber
                    - recording
                    - onHuman
                    - status
                required:
                - data
components:
  schemas:
    DialerCallRecording:
      type: object
      description: One recording of a call (#419). Play it through `mediaUrl` (the authenticated media proxy; add `&download=1` to download).
      required:
      - sid
      - part
      - startedAt
      - durationSeconds
      - primary
      - mediaUrl
      properties:
        sid:
          type:
          - string
          - 'null'
          description: The Twilio RecordingSid; null only on a call recorded before the sid was kept.
        part:
          type:
          - string
          - 'null'
          enum:
          - bridge
          - conference
          - null
          description: 'bridge: before the conference; conference: the conference; null: the call was never upgraded into a conference.'
        startedAt:
          type:
          - string
          - 'null'
          format: date-time
        durationSeconds:
          type:
          - integer
          - 'null'
          description: Seconds, when known; null otherwise.
        primary:
          type: boolean
          description: The call's own recording (the one transcribed).
        mediaUrl:
          type: string
          description: GET /api/v1/dialer/call/{id}/media?type=recording[&sid=...]
    DataEnvelope:
      type: object
      properties:
        data:
          description: Response payload (shape varies by endpoint)
  parameters:
    IdParam:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Resource UUID
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'API key authentication. Generate keys in Settings > API Keys.

        Keys use the `cdy_` prefix.


        Example: `Authorization: Bearer cdy_a1b2c3d4e5f6...`

        '
x-mcp:
  transport:
  - stdio
  - http
  orchestration: code
  endpoint_tools: hidden