> ## Documentation Index > Fetch the complete documentation index at: https://docs.tetherai.ca/llms.txt > Use this file to discover all available pages before exploring further. # Ingest an externally completed call record > Public ingestion endpoint for vendor-agnostic external calling systems to push completed call records into Tether. Authenticated via a user-scoped API key (Bearer token from `GET /api/user/api-key`) — does NOT use the standard JWT auth. Creates the same `Contact` / `Conversation` / `Call` / recording artifacts as the ElevenLabs post-call webhook. Idempotent on `externalCallId`. Uploads recordings (base64 MP3 or URL) to R2. Emits `call_initiated`, `call_ended`, `call_recording_ready`, and `fetch_messages` socket events. ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/calls/ingest openapi: 3.0.3 info: title: Tether Relay and Tether API version: 1.0.0 description: >- Route-derived OpenAPI contract generated from tether-relay backend sources. Regenerate with scripts/sync-openapi-from-backend.mjs. servers: - url: https://your-instance.example.com description: Production - url: http://localhost:2212 description: Local API service security: [] tags: - name: AI - name: Applications - name: Approval - name: Auth - name: Automations - name: Calls - name: Campaigns - name: Contact Analytics - name: Contact Metrics - name: Contact Notes - name: Contacts - name: Conversation Monitor - name: Conversations - name: Departments - name: Email - name: Escalation Dashboard - name: Event Logs - name: Google Sheets - name: Marketplace - name: Messages - name: Notification Sounds - name: Notifications - name: Org Snapshots - name: Organizations - name: Outreach - name: Outreach Metrics - name: Outreach Sources - name: Pipelines - name: Processes - name: Prompts - name: Reminders - name: Sms - name: Templates - name: Traces - name: Training - name: Upload - name: User Snapshots - name: Users - name: Vertical - name: Webchats - name: Webhook paths: /api/calls/ingest: post: tags: - Calls summary: Ingest an externally completed call record description: >- Public ingestion endpoint for vendor-agnostic external calling systems to push completed call records into Tether. Authenticated via a user-scoped API key (Bearer token from `GET /api/user/api-key`) — does NOT use the standard JWT auth. Creates the same `Contact` / `Conversation` / `Call` / recording artifacts as the ElevenLabs post-call webhook. Idempotent on `externalCallId`. Uploads recordings (base64 MP3 or URL) to R2. Emits `call_initiated`, `call_ended`, `call_recording_ready`, and `fetch_messages` socket events. operationId: post_calls_ingest requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CallsIngestExternalCallRequest' responses: '200': description: Duplicate detected via externalCallId — existing record returned content: application/json: schema: $ref: '#/components/schemas/CallsIngestDedupResponse' '201': description: Call ingested content: application/json: schema: $ref: '#/components/schemas/CallsIngestCreatedResponse' '400': description: Validation error or recording could not be processed content: application/json: schema: $ref: '#/components/schemas/CallsIngestErrorResponse' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/CallsIngestErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/CallsIngestErrorResponse' security: - bearerAuth: [] components: schemas: CallsIngestExternalCallRequest: type: object description: >- Vendor-agnostic completed-call payload. `transcript`, `summary`, and `recording` are required when `status === "completed"`. properties: direction: type: string enum: - inbound - outbound fromNumber: type: string description: E.164 (e.g. +14155551234). toNumber: type: string description: E.164. duration: type: number description: Call duration in seconds (non-negative). status: type: string enum: - completed - no-answer - busy - failed transcript: type: array description: >- Structured transcript (required when status is "completed"). Plain text is not accepted. items: $ref: '#/components/schemas/CallsIngestTranscriptTurn' summary: type: string description: Required when status is "completed". recording: type: string description: >- Required when status is "completed". Base64-encoded MP3 (optionally with a `data:audio/...;base64,` prefix) or a publicly downloadable URL. externalCallId: type: string description: Optional external identifier used for idempotency. agentName: type: string description: Name of the external AI agent. metadata: type: object description: Arbitrary vendor metadata (stored on `providerMetadata.metadata`). additionalProperties: true callerName: type: string description: >- Used to backfill placeholder contact name when the contact was newly created as "Unknown Caller". callStartTime: type: string format: date-time description: ISO start time; defaults to now. required: - direction - fromNumber - toNumber - duration - status additionalProperties: true example: direction: outbound fromNumber: '+14165550100' toNumber: '+14165550199' duration: 154 status: completed transcript: - role: agent message: Hi, this is Alex from Example Corp. timestamp: 0.5 - role: user message: Hey Alex. timestamp: 2.8 summary: Confirmed appointment for Friday at 2pm. recording: https://vendor.example/recordings/abc123.mp3 externalCallId: vendor-call-abc123 agentName: Alex (Example Agent) callStartTime: '2026-05-15T09:10:00.000Z' CallsIngestDedupResponse: type: object properties: success: type: boolean enum: - true deduplicated: type: boolean enum: - true callId: type: string required: - success - deduplicated - callId additionalProperties: true example: success: true deduplicated: true callId: 64f0a1b2c3d4e5f6a7b8cb00 CallsIngestCreatedResponse: type: object properties: success: type: boolean enum: - true callId: type: string description: Tether Call._id. contactId: type: string conversationId: type: string required: - success - callId - contactId - conversationId additionalProperties: true example: success: true callId: 64f0a1b2c3d4e5f6a7b8cb00 contactId: 64f0a1b2c3d4e5f6a7b8c9d0 conversationId: 64f0a1b2c3d4e5f6a7b8c9e0 CallsIngestErrorResponse: type: object properties: success: type: boolean enum: - false error: type: string required: - success - error additionalProperties: true example: success: false error: 'Missing required field: transcript' CallsIngestTranscriptTurn: type: object properties: role: type: string enum: - agent - user message: type: string timestamp: type: number description: Optional seconds-into-call. required: - role - message additionalProperties: false example: role: agent message: Hi, this is Alex from Example Corp. timestamp: 0.5 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````