List Calls

curl -X GET "https://api.contactship.ai/v1/calls?limit=20&offset=0" \
  -H "x-api-key: your-api-key"

curl -X GET "https://api.contactship.ai/v1/calls?limit=10&call_result=answered&date_from=2026-01-01&include_transcript=true" \
  -H "x-api-key: your-api-key"

const listCalls = async (params = {}) => {
  const query = new URLSearchParams(params).toString();
  const response = await fetch(
    `https://api.contactship.ai/v1/calls${query ? `?${query}` : ''}`,
    { headers: { 'x-api-key': 'your-api-key' } }
  );
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
};

// Example: get the last 10 answered calls
const result = await listCalls({
  limit: 10,
  call_result: 'answered',
  date_from: '2026-01-01',
});
console.log(`${result.data.length} calls, ${result.pagination.total_rows} total`);

import requests

api_key = "your-api-key"

params = {
    "limit": 10,
    "call_result": "answered",
    "date_from": "2026-01-01",
}

response = requests.get(
    "https://api.contactship.ai/v1/calls",
    headers={"x-api-key": api_key},
    params=params,
)

if response.status_code == 200:
    result = response.json()
    print(f"{len(result['data'])} calls returned, {result['pagination']['total_rows']} total")
else:
    print(f"Error {response.status_code}: {response.text}")

{
  "statusCode": 200,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "direction": "outbound",
      "from": "+12025551234",
      "call_record": "https://api.contactship.ai/recordings/a1b2c3d4.mp3",
      "call_status": "completed",
      "call_result": "answered",
      "disconnection_reason": "agent_hangup",
      "finished_at": "2026-03-15T14:35:22Z",
      "start_at": "2026-03-15T14:30:05Z",
      "duration": 317,
      "call_analysis": {
        "summary": "Customer expressed interest in the premium plan and requested a demo.",
        "sentiment": "positive"
      },
      "type": "ai_call",
      "created_at": "2026-03-15T14:30:00Z",
      "agent_id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "campaign_id": null,
      "contact": {
        "id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
        "full_name": "Jane Smith",
        "phone_number": "+14155552678",
        "email": "jane.smith@example.com",
        "country": "US"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "total_rows": 142,
    "total_pages": 3
  }
}

GET

calls

curl -X GET "https://api.contactship.ai/v1/calls?limit=20&offset=0" \
  -H "x-api-key: your-api-key"

curl -X GET "https://api.contactship.ai/v1/calls?limit=10&call_result=answered&date_from=2026-01-01&include_transcript=true" \
  -H "x-api-key: your-api-key"

const listCalls = async (params = {}) => {
  const query = new URLSearchParams(params).toString();
  const response = await fetch(
    `https://api.contactship.ai/v1/calls${query ? `?${query}` : ''}`,
    { headers: { 'x-api-key': 'your-api-key' } }
  );
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
};

// Example: get the last 10 answered calls
const result = await listCalls({
  limit: 10,
  call_result: 'answered',
  date_from: '2026-01-01',
});
console.log(`${result.data.length} calls, ${result.pagination.total_rows} total`);

import requests

api_key = "your-api-key"

params = {
    "limit": 10,
    "call_result": "answered",
    "date_from": "2026-01-01",
}

response = requests.get(
    "https://api.contactship.ai/v1/calls",
    headers={"x-api-key": api_key},
    params=params,
)

if response.status_code == 200:
    result = response.json()
    print(f"{len(result['data'])} calls returned, {result['pagination']['total_rows']} total")
else:
    print(f"Error {response.status_code}: {response.text}")

{
  "statusCode": 200,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "direction": "outbound",
      "from": "+12025551234",
      "call_record": "https://api.contactship.ai/recordings/a1b2c3d4.mp3",
      "call_status": "completed",
      "call_result": "answered",
      "disconnection_reason": "agent_hangup",
      "finished_at": "2026-03-15T14:35:22Z",
      "start_at": "2026-03-15T14:30:05Z",
      "duration": 317,
      "call_analysis": {
        "summary": "Customer expressed interest in the premium plan and requested a demo.",
        "sentiment": "positive"
      },
      "type": "ai_call",
      "created_at": "2026-03-15T14:30:00Z",
      "agent_id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "campaign_id": null,
      "contact": {
        "id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
        "full_name": "Jane Smith",
        "phone_number": "+14155552678",
        "email": "jane.smith@example.com",
        "country": "US"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "total_rows": 142,
    "total_pages": 3
  }
}

Returns a paginated list of calls for your organization. By default, chat_history (transcript) is not included — pass include_transcript=true to include it. Supports filtering by date range, status, result, agent, and campaign.

Headers

string

requerido

Your API key for authentication. Found in your dashboard under API settings.

Query Parameters

number

predeterminado:"20"

Maximum number of calls to return. Must be ≥ 0.

number

predeterminado:"0"

Number of records to skip for pagination. Must be ≥ 0.

string

predeterminado:"desc"

Sort direction by creation date. Possible values: asc, desc.

string

Filter calls created on or after this date (ISO 8601, e.g. 2026-01-01).

string

Filter calls created on or before this date (ISO 8601, e.g. 2026-04-01).

string

Filter by call status. Possible values: in-progress, completed, no-answer, failed, in-queue, incomplete, busy, answering-machine, scheduled, voice_mail.

string

Filter by call result. Possible values: answered, voicemail, no_answer, busy, failed.

string

Filter by agent UUID.

string

Filter by campaign UUID.

string

Filter by phone number in E.164 format (e.g. +12124567890).

boolean

predeterminado:"false"

Include chat_history (transcript) in each call record. Defaults to false.

boolean

predeterminado:"false"

Include per-word timing data in transcript entries. Only applies when include_transcript=true.

boolean

predeterminado:"false"

Include chat_history_with_tools in each call record.

string

predeterminado:"json"

Format for transcript output. Possible values: json (raw array), toon (token-efficient TOON encoding). Only applies when include_transcript=true or include_tools=true.

Response

The response contains statusCode, a data array, and pagination with page, total_rows, and total_pages.

array

Array of call objects.

Mostrar Call object

string

Unique identifier of the call (UUID).

string

Call direction: inbound or outbound.

string

The phone number that initiated the call (E.164 format).

string

URL to the call recording, if available.

string

Current status of the call (e.g. completed, no-answer, failed).

string

Outcome of the call (e.g. answered, voicemail, no_answer).

string

Reason the call was disconnected, if applicable.

string

Timestamp when the call ended (ISO 8601).

string

Timestamp when the call started (ISO 8601).

number

Call duration in seconds.

object

AI-generated analysis of the call (summary, sentiment, etc.).

string

Call type identifier.

string

Timestamp when the call record was created (ISO 8601).

string

UUID of the AI agent that handled the call.

string

UUID of the campaign this call belongs to, if any.

object

Contact associated with the call.

Mostrar Contact object

string

Contact UUID.

string

Contact full name.

string

Contact phone number.

string

Contact email address.

string

Contact country code.

array or string

Transcript of the call. Present only when include_transcript=true. Returns an array of transcript entries (JSON format) or a TOON-encoded string when transcript_format=toon.

array or string

Transcript including tool calls. Present only when include_tools=true.

string

Format used for transcript fields. Present when transcript is included.

object

Pagination metadata: page, total_rows, and total_pages.

Error Codes

400 Bad Request — Invalid query parameters
401 Unauthorized — Invalid or missing API key
429 Too Many Requests — Rate limit exceeded; honor Retry-After when present and use bounded backoff. See Rate Limits
500 Internal Server Error — Server-side error

Code Examples

curl -X GET "https://api.contactship.ai/v1/calls?limit=20&offset=0" \
  -H "x-api-key: your-api-key"

curl -X GET "https://api.contactship.ai/v1/calls?limit=10&call_result=answered&date_from=2026-01-01&include_transcript=true" \
  -H "x-api-key: your-api-key"

const listCalls = async (params = {}) => {
  const query = new URLSearchParams(params).toString();
  const response = await fetch(
    `https://api.contactship.ai/v1/calls${query ? `?${query}` : ''}`,
    { headers: { 'x-api-key': 'your-api-key' } }
  );
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
};

// Example: get the last 10 answered calls
const result = await listCalls({
  limit: 10,
  call_result: 'answered',
  date_from: '2026-01-01',
});
console.log(`${result.data.length} calls, ${result.pagination.total_rows} total`);

import requests

api_key = "your-api-key"

params = {
    "limit": 10,
    "call_result": "answered",
    "date_from": "2026-01-01",
}

response = requests.get(
    "https://api.contactship.ai/v1/calls",
    headers={"x-api-key": api_key},
    params=params,
)

if response.status_code == 200:
    result = response.json()
    print(f"{len(result['data'])} calls returned, {result['pagination']['total_rows']} total")
else:
    print(f"Error {response.status_code}: {response.text}")

{
  "statusCode": 200,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "direction": "outbound",
      "from": "+12025551234",
      "call_record": "https://api.contactship.ai/recordings/a1b2c3d4.mp3",
      "call_status": "completed",
      "call_result": "answered",
      "disconnection_reason": "agent_hangup",
      "finished_at": "2026-03-15T14:35:22Z",
      "start_at": "2026-03-15T14:30:05Z",
      "duration": 317,
      "call_analysis": {
        "summary": "Customer expressed interest in the premium plan and requested a demo.",
        "sentiment": "positive"
      },
      "type": "ai_call",
      "created_at": "2026-03-15T14:30:00Z",
      "agent_id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "campaign_id": null,
      "contact": {
        "id": "c1d2e3f4-a5b6-7890-cdef-123456789012",
        "full_name": "Jane Smith",
        "phone_number": "+14155552678",
        "email": "jane.smith@example.com",
        "country": "US"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "total_rows": 142,
    "total_pages": 3
  }
}

Documentación API

Voz

WhatsApp (WABA)

Canales y conversaciones

Organización

Agentes

Contactos

Eventos

Etiquetas

Llamadas

Tareas

Números de teléfono

Headers

Query Parameters

Response

Error Codes

Code Examples

​Headers

​Query Parameters

​Response

​Error Codes

​Code Examples

Headers

Query Parameters

Response

Error Codes

Code Examples