> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amplemarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Calls
> Learn how to manage calls via API
The calls API allows you to:
* List calls
* Log calls (create call records)
* Get call dispositions
* Retrieve call recordings
A typical flow includes:
1. Logging a call via `POST /calls` after it's completed (to record calls made outside Amplemarket)
2. Optionally setting a disposition to categorize the call outcome
3. Retrieving call recordings via `GET /calls/{id}/recording` for analysis or compliance purposes
Calls can be logged with various metadata including duration, transcription, recording URLs, and dispositions to help track and analyze your outreach efforts.
# Call Object
| Field | Type | Description |
| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | string (uuid) | The ID of the call |
| `from` | string | The phone number that initiated the call |
| `to` | string | The phone number that received the call |
| `duration` | integer | The duration of the call in seconds |
| `answered` | boolean | Whether the call was answered |
| `human` | boolean | Whether a human answered the call or if it was detected as a machine/voicemail |
| `transcription` | string or null | The text representation of the call's audio, if available |
| `notes` | string or null | Custom notes associated with the call |
| `recording_url` | string | URL to the call recording (if available) |
| `disposition_id` | string (uuid) | Call disposition ID. The disposition action determines behavior: "complete" marks the task and lead as completed, while "next\_stage" takes no action purposefully - read more below |
| `task_id` | string (uuid) | The ID of the task associated with this call |
| `user_id` | string (uuid) | The ID of the user who made the call |
| `external` | boolean | Whether the call was made externally (outside of Amplemarket) |
| `contact` | object or null | The contact associated with this call (see below) |
| `start_date` | string (date-time) | The start date and time of the call in ISO 8601 format |
### Contact Object
| Field | Type | Description |
| ------- | -------------- | ---------------------------- |
| `id` | string (uuid) | The ID of the contact |
| `name` | string or null | The full name of the contact |
| `email` | string or null | The email of the contact |
## Example Call Object
```json theme={null}
{
"id": "0199ba5b-e387-7d61-8ae4-6ad9ce65f07b",
"disposition_id": "0199ba5b-e20c-7dc1-9481-097d1256e75b",
"duration": 5,
"external": true,
"start_date": "2025-10-06T16:30:08Z",
"from": "+1 123456789",
"to": "+1 123456789",
"notes": null,
"transcription": null,
"task_id": "0199ba5b-e332-77e3-8f73-b86f921ad681",
"user_id": "0199ba5b-e2fd-764a-9f21-5df8758d5dd3",
"human": false,
"answered": true,
"contact": {
"id": "0199ba5b-e123-7abc-8def-123456789012",
"name": "John Doe",
"email": "john.doe@example.com"
}
}
```
# Logging Calls
To log a call, send a `POST` request to `/calls` with the following required fields:
* `from` (string, required) - The phone number that initiated the call
* `to` (string, required) - The phone number that received the call
* `duration` (integer, required) - The duration of the call in seconds
* `answered` (boolean, required) - Whether the call was answered
* `human` (boolean, required) - Whether a human answered or if it was a machine/voicemail
* `task_id` (string uuid, required) - The ID of the task associated with the call
* `user_id` (string uuid, required) - The ID of the user making the call
Optional fields:
* `transcription` (string) - The text transcription of the call
* `recording_url` (string) - URL to the call recording
* `disposition_id` (string uuid) - Call disposition ID to categorize the outcome
## Example Request
```bash theme={null}
curl --request POST \
--url https://api.amplemarket.com/calls \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"from": "+1 123456789",
"to": "+1 987654321",
"duration": 120,
"answered": true,
"human": true,
"transcription": "Call transcription here...",
"recording_url": "https://example.com/recording.mp3",
"disposition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}'
```
# Call Dispositions
When logging a call, you can optionally include a `disposition_id` to categorize the outcome and trigger the appropriate action.
Call dispositions allow you to categorize the outcome of calls. You can retrieve available dispositions using the `GET /calls/dispositions` endpoint.
Dispositions have different actions that determine how the system responds:
* **`next_stage`** - No automatic action is taken. This allows your integration to repeat the call or schedule another attempt if needed. The task and lead remain in their current state. You can manually [complete the task](/guides/tasks) when ready.
* **`complete`** - The associated task and sequence lead will automatically be marked as completed. Use this when the call objective has been achieved and no further attempts are needed.
# Call Recordings
For advanced call analysis workflows, see the [Call Recordings guide](/guides/call-recordings) to learn how to automatically retrieve and analyze call recordings using webhooks and third-party services.