GET
/
v1
/
contacts
/
{contactId}
/
calls
# Retrieve all call history for a contact
curl -X GET "https://api.contactship.ai/v1/contacts/c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6/calls" \
  -H "x-api-key: your-api-key"

[
  {
    "id": "d5e6f7g8-h9i0-j1k2-l3m4-n5o6p7q8r9s0",
    "created_at": "2023-03-15T14:35:00Z",
    "call_time": "2023-03-15T14:30:00Z",
    "duration": 245,
    "direction": "outbound",
    "status": "answered",
    "notes": "Cliente interesado en el plan premium, solicita demostración",
    "recording_url": "https://api.contactship.ai/recordings/d5e6f7g8-h9i0-j1k2-l3m4-n5o6p7q8r9s0.mp3",
    "contact_id": "c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6",
    "user_id": "u1v2w3x4-y5z6-a7b8-c9d0-e1f2g3h4i5j6",
    "organization_id": "org123456"
  },
  {
    "id": "f7g8h9i0-j1k2-l3m4-n5o6-p7q8r9s0t1u2",
    "created_at": "2023-02-20T10:15:00Z",
    "call_time": "2023-02-20T10:10:00Z",
    "duration": 180,
    "direction": "inbound",
    "status": "answered",
    "notes": "Cliente pidió información sobre precios",
    "recording_url": "https://api.contactship.ai/recordings/f7g8h9i0-j1k2-l3m4-n5o6-p7q8r9s0t1u2.mp3",
    "contact_id": "c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6",
    "user_id": "u1v2w3x4-y5z6-a7b8-c9d0-e1f2g3h4i5j6",
    "organization_id": "org123456"
  },
  {
    "id": "h9i0j1k2-l3m4-n5o6-p7q8-r9s0t1u2v3w4",
    "created_at": "2023-01-10T15:45:00Z",
    "call_time": "2023-01-10T15:40:00Z",
    "duration": 0,
    "direction": "outbound",
    "status": "missed",
    "notes": "No contestó, intentar más tarde",
    "recording_url": null,
    "contact_id": "c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6",
    "user_id": "u1v2w3x4-y5z6-a7b8-c9d0-e1f2g3h4i5j6",
    "organization_id": "org123456"
  }
]

This endpoint allows you to retrieve the complete call history for a specific contact, including incoming and outgoing calls, call duration, timestamps, and call status information. This data is useful for tracking communications, analyzing engagement patterns, and maintaining a complete interaction record.

​
Use Cases

  • Review all previous calls with a contact
  • Track frequency and duration of communications
  • Analyze communication patterns for customer engagement
  • Provide customer service representatives with historical context
  • Generate reports on communication frequency and outcomes

​
Path Parameters

​
contactId
string
required

The unique identifier of the contact whose call history you want to retrieve. This is a UUID string that was generated when the contact was created.

​
Headers

​
x-api-key
string
required

Your API key for authentication. You can find this in your dashboard under API settings.

​
Query Parameters

​
start_date
string

Filter calls that occurred on or after this date (ISO 8601 format, e.g., 2023-01-01). If not specified, returns all calls from the beginning.

​
end_date
string

Filter calls that occurred on or before this date (ISO 8601 format, e.g., 2023-12-31). If not specified, returns all calls up to the current date.

​
direction
string

Filter calls by direction. Possible values: inbound, outbound. If not specified, returns both inbound and outbound calls.

​
status
string

Filter calls by status. Possible values: answered, missed, rejected, busy, failed. If not specified, returns calls with any status.

​
Response

​
status code
number

200 on success

​
data
array

Array of call records for the contact

​
Error Codes

  • 400 Bad Request - Invalid query parameters
  • 401 Unauthorized - Invalid or missing API key
  • 404 Not Found - Contact not found
  • 500 Internal Server Error - Server-side error

​
Code Examples

# Retrieve all call history for a contact
curl -X GET "https://api.contactship.ai/v1/contacts/c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6/calls" \
  -H "x-api-key: your-api-key"

[
  {
    "id": "d5e6f7g8-h9i0-j1k2-l3m4-n5o6p7q8r9s0",
    "created_at": "2023-03-15T14:35:00Z",
    "call_time": "2023-03-15T14:30:00Z",
    "duration": 245,
    "direction": "outbound",
    "status": "answered",
    "notes": "Cliente interesado en el plan premium, solicita demostración",
    "recording_url": "https://api.contactship.ai/recordings/d5e6f7g8-h9i0-j1k2-l3m4-n5o6p7q8r9s0.mp3",
    "contact_id": "c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6",
    "user_id": "u1v2w3x4-y5z6-a7b8-c9d0-e1f2g3h4i5j6",
    "organization_id": "org123456"
  },
  {
    "id": "f7g8h9i0-j1k2-l3m4-n5o6-p7q8r9s0t1u2",
    "created_at": "2023-02-20T10:15:00Z",
    "call_time": "2023-02-20T10:10:00Z",
    "duration": 180,
    "direction": "inbound",
    "status": "answered",
    "notes": "Cliente pidió información sobre precios",
    "recording_url": "https://api.contactship.ai/recordings/f7g8h9i0-j1k2-l3m4-n5o6-p7q8r9s0t1u2.mp3",
    "contact_id": "c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6",
    "user_id": "u1v2w3x4-y5z6-a7b8-c9d0-e1f2g3h4i5j6",
    "organization_id": "org123456"
  },
  {
    "id": "h9i0j1k2-l3m4-n5o6-p7q8-r9s0t1u2v3w4",
    "created_at": "2023-01-10T15:45:00Z",
    "call_time": "2023-01-10T15:40:00Z",
    "duration": 0,
    "direction": "outbound",
    "status": "missed",
    "notes": "No contestó, intentar más tarde",
    "recording_url": null,
    "contact_id": "c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6",
    "user_id": "u1v2w3x4-y5z6-a7b8-c9d0-e1f2g3h4i5j6",
    "organization_id": "org123456"
  }
]

​
Notes and Best Practices

  • Use date filtering to narrow down results for contacts with extensive call histories
  • Store call IDs if you need to reference specific calls in the future
  • Consider implementing caching for frequently accessed call histories
  • Use the call history data to identify patterns in customer communication
  • Monitor call durations and frequencies to optimize customer engagement strategies