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_ description: 'Personal API key from Settings → API Keys. Code samples show `Authorization: Bearer ` — replace `` 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.