iCallAgent Public API Contacts API

openapi: 3.2.0
info:
  title: iCallAgent Public Contacts API
  version: '1'
servers:
- url: http://127.0.0.1:8000/api/public/v1
  description: Local development
- url: https://api.icallagent.com/api/public/v1
  description: Production
tags:
- name: Contacts
paths:
  /contacts/:
    get:
      operationId: searchContacts
      description: Powers Make's "Search Contacts" lookup module. Only outbound-usage contacts are searched. Deliberately returns every match rather than guessing a single best one — a name is often ambiguous (multiple "Stephan"s), so the caller is expected to disambiguate when more than one result comes back.
      summary: Search contacts
      parameters:
      - in: query
        name: limit
        schema:
          type: integer
        description: Max results to return. Default 100, clamped to [1, 200] — out-of-range values are silently clamped, not rejected.
      - in: query
        name: offset
        schema:
          type: integer
        description: Number of results to skip. Default 0. Negative values are clamped to 0.
      - in: query
        name: q
        schema:
          type: string
        description: Case-insensitive substring match against name OR phone. Omit to list all outbound contacts.
      tags:
      - Contacts
      security:
      - ApiKeyAuth: []
      - oauth2: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    description: Matching outbound contacts (all matches — not ranked).
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Contact id in your workspace.
                        name:
                          type: string
                          description: Contact display name (may be empty).
                        phone:
                          type: string
                          description: Normalized phone number on the contact.
                        company:
                          type: string
                          description: Company field if set (may be empty).
                        notes:
                          type: string
                          description: Free-form notes on the contact (may be empty).
              examples:
                OK:
                  value:
                    results:
                    - id: 44
                      name: Stephan Kim
                      phone: '+15557890123'
                      company: Acme Co
                      notes: ''
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Human-readable error message. Same shape on all public API errors.
              examples:
                NoWorkspace:
                  value:
                    detail: No workspace is connected for this application. Reconnect and select a workspace.
                  summary: No workspace
          description: No workspace resolved for this caller (OAuth2 app not connected to a workspace, or the API key's workspace no longer exists).
    post:
      operationId: createContact
      description: 'Upserts a Contact by (workspace, phone) and enqueues a ScheduledCall against a campaign. Powers Make''s "Send Contact" module.


        **Evaluated in this order — which step fails determines the status code:**

        1. `phone` missing or unnormalizable → 400

        2. Campaign resolution: neither `campaign_id` nor `campaign` given → 400; not found → 404; `campaign` (name) matches more than one campaign → 409 (use `campaign_id` instead)

        3. Campaign status isn''t draft/active/paused → 409 (not accepting new contacts)

        4. `external_id` already seen for this campaign → **200** (not 201) with the existing row, untouched — idempotent replay

        5. Contact upserted by (workspace, phone)

        6. Compliance gate (blacklist/DNC/consent) fails → 422, no call scheduled

        7. ScheduledCall created → 201


        `campaign_id` wins if both `campaign_id` and `campaign` are given. An invalid `consent_status` silently falls back to `implied` rather than being rejected.'
      summary: Send a contact / queue a call
      tags:
      - Contacts
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactCreateRequest'
            examples:
              QueueACall:
                value:
                  phone: '+15550101999'
                  campaign_id: 13
                  name: Jane Doe
                  company: Acme
                  consent_status: implied
                  external_id: docs-demo-001
                summary: Contact + campaign by id
                description: campaign_id 13 is Support Follow-ups on the local docs workspace if present; use any campaign id from List campaigns.
        required: true
      security:
      - ApiKeyAuth: []
      - oauth2: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact_id:
                    type: integer
                    description: Id of the contact row in your workspace (upserted by phone). Reuse this id when searching or correlating CRM records.
                  scheduled_call_id:
                    type: integer
                    description: Id of the scheduled outbound call. On **200** this is the existing call from the first `external_id` request (not a new one).
                  campaign_id:
                    type: integer
                    description: Campaign the call is queued on (same as request `campaign_id` / resolved name).
                  status:
                    type: string
                    description: Current dial-queue status of the scheduled call. Newly queued (or replayed) calls return `pending` until the scheduler places them.
                    examples:
                    - pending
                required:
                - contact_id
                - scheduled_call_id
                - campaign_id
                - status
              examples:
                IdempotentReplay:
                  value:
                    contact_id: 44
                    scheduled_call_id: 901
                    campaign_id: 12
                    status: pending
                  summary: Idempotent replay
          description: 'Idempotent replay: this campaign already has a call for the given `external_id`. The same four fields as 201 — existing row, not mutated.'
        '201':
          content:
            application/json:
              schema:
                type: object
                properties:
                  contact_id:
                    type: integer
                    description: Id of the contact row in your workspace (upserted by phone). Reuse this id when searching or correlating CRM records.
                  scheduled_call_id:
                    type: integer
                    description: Id of the scheduled outbound call. On **200** this is the existing call from the first `external_id` request (not a new one).
                  campaign_id:
                    type: integer
                    description: Campaign the call is queued on (same as request `campaign_id` / resolved name).
                  status:
                    type: string
                    description: Current dial-queue status of the scheduled call. Newly queued (or replayed) calls return `pending` until the scheduler places them.
                    examples:
                    - pending
                required:
                - contact_id
                - scheduled_call_id
                - campaign_id
                - status
              examples:
                Created:
                  value:
                    contact_id: 45
                    scheduled_call_id: 902
                    campaign_id: 12
                    status: pending
          description: Contact upserted (or matched by phone) and a new scheduled call was queued. Same response shape as 200.
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Human-readable error message. Same shape on all public API errors.
              examples:
                BadPhone:
                  value:
                    detail: A valid phone number is required.
                  summary: Bad phone
          description: Invalid/missing phone, or neither campaign_id nor campaign given.
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Human-readable error message. Same shape on all public API errors.
              examples:
                NotFound:
                  value:
                    detail: Campaign not found.
                  summary: Not found
          description: Campaign not found.
        '409':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Human-readable error message. Same shape on all public API errors.
              examples:
                AmbiguousName:
                  value:
                    detail: More than one campaign matches that name; use campaign_id instead.
                  summary: Ambiguous name
          description: Ambiguous campaign name, or campaign not accepting new contacts.
        '422':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Human-readable error message. Same shape on all public API errors.
              examples:
                ComplianceBlocked:
                  value:
                    detail: This number is on the do-not-call list.
                  summary: Compliance blocked
          description: Blocked by the compliance gate (blacklist, do-not-call, or consent). The contact is still upserted; no call is scheduled.
components:
  schemas:
    ContactCreateRequest:
      type: object
      properties:
        phone:
          type: string
          description: Destination number in any format the platform can normalize (US-friendly forms or E.164). Missing/invalid → **400**.
        campaign_id:
          type: integer
          description: Campaign to queue against. Wins over `campaign` if both are given. Prefer this when you already know the id from List campaigns.
        campaign:
          type: string
          description: Campaign name, exact match. Ambiguous names return **409** — use `campaign_id` instead. One of `campaign_id` or `campaign` is required.
        name:
          type: string
          description: Contact display name (CRM / agent context).
        email:
          type: string
          description: Optional email. Not used for dialing.
        company:
          type: string
          description: Optional company name.
        department:
          type: string
          description: Optional department / team label.
        notes:
          type: string
          description: Free-form notes for your records or agent tools.
        consent_status:
          type: string
          description: Compliance consent marker (e.g. `implied`, `express`, `unknown`). Invalid values silently fall back to `implied`.
        external_id:
          type: string
          description: Idempotency key, scoped to the campaign. Replaying the same `external_id` returns the original call with **200** instead of a duplicate.
      required:
      - phone
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: ic_live_<token>
      description: 'Personal API key from Settings → API Keys. Code samples show `Authorization: Bearer <token>` — replace `<token>` with your key (include the word Bearer).'
    oauth2:
      type: oauth2
      description: OAuth2 access token from the consent flow third-party apps go through (see /oauth/authorize/). Interchangeable with a personal API key on every operation below — both are sent as a Bearer token in the same header.
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize/
          tokenUrl: /oauth/token/
          scopes:
            campaigns:read: List your call campaigns
            campaigns:write: Create new call campaigns
            contacts:write: Create contacts and queue calls into your campaigns
x-snapshot-note: SNAPSHOT — do not hand-edit. Regenerate with `npm run api:sync`, which fetches /api/public/v1/schema/ from the backend. It is committed so Vercel builds are reproducible and do not depend on the backend being reachable.