Allo - AI Phone System for Small Teams

https://help.withallo.com
Admin
API for Allo, an AI-powered phone system for small sales teams. Automate call data retrieval with AI...
Tokens:129,697
Snippets:776
Trust Score:8.5
Update:2 months ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
-   API key goes directly in the Authorization header without Bearer prefix. Example: Authorization: sk_your_api_key
-   All API requests go to https://api.withallo.com
-   Phone numbers must be in E.164 format with country code and + prefix (e.g., +14155551234)
-   US numbers use POST /v1/api/sms, French numbers use POST /v1/api/sms with a sender_id
-   Each webhook configuration is tied to a specific Allo phone number
-   Daily rate limits apply. On 429 errors, check the reset_in field for seconds until reset. Use exponential backoff.
-   Different endpoints require specific scopes: WEBHOOKS_READ_WRITE, CONVERSATIONS_READ, CONTACTS_READ, SMS_SEND
-   To get a contact's conversation history, first retrieve the contact_id by searching contacts via GET /v1/api/contacts, then use GET /v1/api/contact/{contact_id}/conversation. Contact IDs have the format cnt_abc123.

================
CODE SNIPPETS
================
### Get Me Response Example

Source: https://help.withallo.com/en/v2/api-reference/users/me

Example JSON response returned by the getMe endpoint containing API key metadata and available endpoints.

```json
{
  "data": {
    "api_key_id": "api-abc123def456",
    "scopes": [
      "CONVERSATIONS_READ",
      "PHONE_NUMBERS_READ",
      "TAGS_READ",
      "TAGS_WRITE",
      "USERS_READ"
    ],
    "endpoints": [
      {
        "method": "GET",
        "path": "/v2/api/conversations",
        "description": "List conversations grouped by contact number",
        "scope": "CONVERSATIONS_READ"
      },
      {
        "method": "POST",
        "path": "/v2/api/conversations/items/search",
        "description": "Search calls and SMS with filters and keyword search",
        "scope": "CONVERSATIONS_READ"
      },
      {
        "method": "GET",
        "path": "/v2/api/tags",
        "description": "List all available tags",
        "scope": "TAGS_READ"
      },
      {
        "method": "GET",
        "path": "/v2/api/users",
        "description": "List team members with roles and assigned numbers",
        "scope": "USERS_READ"
      },
      {
        "method": "GET",
        "path": "/v2/api/numbers",
        "description": "List phone numbers with capabilities and member access",
        "scope": "PHONE_NUMBERS_READ"
      }
    ],
    "team": {
      "id": "team-xyz789",
      "name": "Acme Sales"
    },
    "rate_limits": {
      "read_per_second": 20,
      "write_per_second": 5
    }
  }
}
```

--------------------------------

### Create Tag Response Example

Source: https://help.withallo.com/en/v2/api-reference/tags/create-tag

Example JSON response returned upon successful tag creation.

```json
{
  "data": {
    "id": "interested",
    "name": "Interested",
    "color": "#123456"
  }
}
```

--------------------------------

### Search people request body example

Source: https://help.withallo.com/en/v2/api-reference/crm/search-people

Example payload demonstrating how to apply filters, sorting, and pagination parameters.

```json
{
  "filters": {
    "job_title": "engineer",
    "company": "Acme"
  },
  "sort": "NAME_ASC",
  "page": 1,
  "size": 20
}
```

--------------------------------

### Reset dialing queue request examples

Source: https://help.withallo.com/en/v2/api-reference/dialing-queues/reset-current

These examples demonstrate the JSON body structure for resetting a queue for yourself or a teammate.

```yaml
name: Monday cold calls
```

```yaml
name: Monday cold calls
user_id: usr-15BB68317A7F06F0C07A3BBD8F244102A6872220
```

```yaml
name: Monday cold calls
email: teammate@acme.com
```

--------------------------------

### Create Tag Request Body Example

Source: https://help.withallo.com/en/v2/api-reference/tags/create-tag

Example JSON payload for creating a new tag.

```json
{
  "name": "Interested",
  "color": "#123456"
}
```

--------------------------------

### List Summary Templates Response Example

Source: https://help.withallo.com/en/v2/api-reference/summary-templates/list-summary-templates

Example JSON response body returned by the listSummaryTemplates operation.

```json
data:
  - id: tst-abc123
    name: Sales call
    call_context: B2B SaaS sales calls
    icon: 📞
    sections:
      - title: Pain points
        instructions: List the prospect's pain points
        order: 0
      - title: Next steps
        instructions: What was agreed
        order: 1
    created_at: '2026-06-01T10:00:00'
    updated_at: '2026-06-01T10:00:00'
```

--------------------------------

### Batch Get Conversation Items Request Example

Source: https://help.withallo.com/en/v2/api-reference/conversations/batch-get

Example JSON payload for requesting multiple conversation items by ID.

```json
ids:
  - cll-abc123
  - cll-def456
  - cll-ghi789
```

--------------------------------

### Unauthorized Error Response Example

Source: https://help.withallo.com/en/v2/api-reference/sms/send-sms

Example response returned when the API key is invalid or missing.

```json
{
            "code": "API_KEY_INVALID",
            "details": null
          }
```

--------------------------------

### Retrieve contact_note.created payload example

Source: https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog

Example JSON payload for the contact_note.created webhook event.

```json
{
  "topic": "contact_note.created",
  "version": "2.0",
  "timestamp": "2026-07-13T10:00:00.000Z",
  "data": {
    "id": "cno-abc123",
    "contact_id": "con-abc123",
    "person_id": "per-abc123",
    "content": "Prefers email over calls. Intro by @[Jane Doe](usr-abc123).",
    "user": {
      "id": "usr-def456",
      "name": "John Smith",
      "email": "john@acme.com"
    },
    "mentions": [
      {
        "user_id": "usr-abc123",
        "name": "Jane Doe"
      }
    ],
    "created_at": "2026-07-13T10:00:00",
    "updated_at": "2026-07-13T10:00:00",
    "deleted": false
  }
}
```

--------------------------------

### Send SMS Request Example

Source: https://help.withallo.com/en/v2/api-reference/sms/send-sms

Example JSON payload for the POST /v1/api/sms request body.

```yaml
from: '+1234567890'
to: '+0987654321'
message: Hello, this is a test message
```

--------------------------------

### Send SMS Success Response Example

Source: https://help.withallo.com/en/v2/api-reference/sms/send-sms

Example JSON response returned upon a successful SMS delivery.

```yaml
data:
  from_number: '+1234567890'
  sender_id: null
  to_number: '+0987654321'
  type: OUTBOUND
  content: Hello, this is a test message
  start_date: '2024-01-15T10:30:00'
```

--------------------------------

### Phone Number Format Examples

Source: https://help.withallo.com/en/v2/api-reference/guides/error-handling

Examples of correct and incorrect phone number formatting for API requests.

```text
+14155551234    ← correct
0612345678      ← wrong (missing country code)
+33 6 12 34 56  ← wrong (contains spaces)
```

--------------------------------

### Search Conversation Items Response Example

Source: https://help.withallo.com/en/v2/api-reference/conversations/search-conversation-items

Example JSON response containing a paginated list of conversation items matching the search criteria.

```json
{
  "data": [
    {
      "id": "cll-abc123",
      "type": "CALL",
      "direction": "INBOUND",
      "allo_number": "+14155550100",
      "contact_number": "+14155551234",
      "contacts": [
        {
          "id": "cnt-abc123",
          "name": "Sarah Johnson"
        }
      ],
      "user": {
        "id": "usr-abc123",
        "name": "Alex Kim"
      },
      "date": "2026-04-21T14:30:00Z",
      "duration": 145,
      "result": "ANSWERED",
      "recording_url": "https://storage.withallo.com/recordings/cll-abc123.mp3",
      "summary": "Customer called about a billing issue on their last\ninvoice.",
      "tags": [
        "billing",
        "support"
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "size": 20,
    "total_count": 1,
    "total_pages": 1,
    "has_more": false
  }
}
```

--------------------------------

### call.received Webhook Payload Example

Source: https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog

Example JSON payload for the call.received event, including contact context when a match is found.

```json
{
  "topic": "call.received",
  "version": "2.0",
  "timestamp": "2025-03-15T14:30:00.000Z",
  "data": {
    "from_number": "+33612345678",
    "to_number": "+33112345678",
    "started_at": "2025-03-15T14:30:00.000Z",
    "user_email": "john@acme.com",
    "person": {
      "id": "con_5MiGNHp2vI1AN6sTu4Cw",
      "name": "Marie",
      "last_name": "Dupont",
      "email": "marie.dupont@acme.com",
      "emails": ["marie.dupont@acme.com"],
      "numbers": ["+33612345678"],
      "job_title": "Head of Sales",
      "linkedin_url": "https://linkedin.com/in/mariedupont",
      "lead_source": "Inbound"
    },
    "company": {
      "id": "com-a1b2c3d4e5f6",
      "name": "Acme Corp"
    },
    "deals": [
      {
        "id": "dea-x1y2z3w4v5u6",
        "name": "Enterprise Plan",
        "status": "qualified",
        "value": 25000.00,
        "currency": "EUR",
        "close_date": "2025-06-15T00:00:00"
      }
    ]
  }
}
```

--------------------------------

### Search Conversation Items Request Example

Source: https://help.withallo.com/en/v2/api-reference/conversations/search-conversation-items

Example JSON payload for searching conversation items by keyword, type, and date range.

```json
{
  "search": "billing issues",
  "type": "CALL",
  "sort": "RELEVANCE",
  "date": {
    "from": "2026-01-01",
    "to": "2026-04-21"
  }
}
```

--------------------------------

### Outbound Analytics Request Example

Source: https://help.withallo.com/en/v2/api-reference/analytics/outbound

Example JSON request body for retrieving outbound call metrics within a specific date range and comparison period.

```json
{
  "date": {
    "from": "2026-03-25",
    "to": "2026-04-21"
  },
  "compare_date": {
    "from": "2026-02-25",
    "to": "2026-03-24"
  },
  "tags": [
    "meeting_booked"
  ],
  "granularity": "DAY"
}
```

--------------------------------

### Current Dialing Queue Response Example

Source: https://help.withallo.com/en/v2/api-reference/dialing-queues/get-current

Example JSON response structure for the current dialing queue, including paginated data and queue metadata.

```json
data:
  - number_to: '+12125550010'
    position: 0
    created_at: '2026-04-30T10:00:00'
    updated_at: '2026-04-30T10:00:00'
    call_start_date: null
    call_id: null
    routing_result: null
    sync_status: NOT_SYNCED
pagination:
  page: 1
  size: 20
  total_count: 137
  total_pages: 7
  has_more: true
queue:
  id: pdl_2xGh7kLmNpQr
  name: My Queue
  creator_id: usr_abc123
  assignee_id: usr_abc123
  voicemail_handling: NO_SKIP
  do_not_disturb: DISABLED
  created_at: '2026-04-30T10:00:00'
  updated_at: '2026-04-30T10:00:00'
```

--------------------------------

### GET /v2/api/webhooks

Source: https://help.withallo.com/en/v2/api-reference/webhooks/get-webhooks

Returns all webhook endpoints configured for your account.

```APIDOC
## GET /v2/api/webhooks

### Description
Returns all webhook endpoints configured for your account.

### Method
GET

### Endpoint
/v2/api/webhooks

### Response
#### Success Response (200)
- **data** (array) - List of webhook endpoints

#### Response Example
{
  "data": [
    {
      "id": "ep_2NfDKEm9sF8xK3pQr1Zt",
      "url": "https://example.com/webhooks/allo",
      "topics": [
        "call.received",
        "sms.received"
      ],
      "description": "Production event stream",
      "enabled": true,
      "created_at": "2026-04-21T14:30:00Z"
    }
  ]
}
```

--------------------------------

### Partner Account Login Webhook Payload

Source: https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog

Example JSON payload for the partner.account.login event, triggered when a reseller-provisioned account logs in for the first time.

```json
{
  "topic": "partner.account.login",
  "version": "2.0",
  "timestamp": "2025-03-15T18:00:00.000Z",
  "data": {
    "account_id": "usr-160F3A46629692CF6E022E09A6217A4F0AD21B45",
    "partner_client_ref": "client-4271",
    "email": "owner@vibrantevents.com",
    "name": "Vibrant Occasions Event Rentals"
  }
}
```

--------------------------------

### Payload structure for conversation_note.created

Source: https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog

Example JSON payload received when an internal note is created in a conversation.

```json
{
  "topic": "conversation_note.created",
  "version": "2.0",
  "timestamp": "2026-07-13T10:00:00.000Z",
  "data": {
    "id": "not-2NyMabc123",
    "content": "Escalate to @[Jane Doe](usr-abc123) tomorrow",
    "allo_number": "+14155550100",
    "contact_number": "+14155551234",
    "user": {
      "id": "usr-def456",
      "name": "John Smith",
      "email": "john@acme.com"
    },
    "mentions": [
      {
        "user_id": "usr-abc123",
        "name": "Jane Doe"
      }
    ],
    "created_at": "2026-07-13T10:00:00",
    "updated_at": "2026-07-13T10:00:00",
    "deleted": false
  }
}
```

--------------------------------

### sms.sent Event Payload

Source: https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog

Example JSON payload for an outbound SMS event.

```json
{
  "topic": "sms.sent",
  "version": "2.0",
  "timestamp": "2025-03-15T16:10:00.000Z",
  "data": {
    "id": "msg_4LhFMGo1uH0zM5rSt3Bv",
    "direction": "OUTBOUND",
    "type": "SMS",
    "content": "Your appointment is confirmed for tomorrow at 2pm.",
    "sent_at": "2025-03-15T16:10:00.000Z",
    "from_number": "+33112345678",
    "to_number": "+33612345678",
    "from_name": "Support Acme",
    "to_name": "Marie Dupont",
    "user_email": "john@acme.com"
  }
}
```

--------------------------------

### call.triggered Event Payload

Source: https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog

Example JSON payload for the call.triggered event, showing the structure of contact, company, and call metadata.

```json
{
  "topic": "call.triggered",
  "version": "2.0",
  "timestamp": "2025-03-15T14:35:00.000Z",
  "data": {
    "from_number": "+33112345678",
    "to_number": "+33612345678",
    "started_at": "2025-03-15T14:35:00.000Z",
    "user_email": "john@acme.com",
    "person": {
      "id": "con_5MiGNHp2vI1AN6sTu4Cw",
      "name": "Marie",
      "last_name": "Dupont",
      "email": "marie.dupont@acme.com",
      "emails": ["marie.dupont@acme.com"],
      "numbers": ["+33612345678"],
      "job_title": "Head of Sales"
    },
    "company": {
      "id": "com-a1b2c3d4e5f6",
      "name": "Acme Corp"
    },
    "deals": null
  }
}
```

--------------------------------

### sms.received Event Payload

Source: https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog

Example JSON payload for an inbound SMS event.

```json
{
  "topic": "sms.received",
  "version": "2.0",
  "timestamp": "2025-03-15T16:00:00.000Z",
  "data": {
    "id": "msg_3KgELFn0tG9yL4qRs2Au",
    "direction": "INBOUND",
    "type": "SMS",
    "content": "Hi, I'd like to schedule an appointment.",
    "sent_at": "2025-03-15T16:00:00.000Z",
    "from_number": "+33612345678",
    "to_number": "+33112345678",
    "from_name": "Marie Dupont",
    "to_name": "Support Acme",
    "user_email": "john@acme.com"
  }
}
```

--------------------------------

### thread.created Webhook Payload

Source: https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog

Example JSON payload for the thread.created event, which is triggered when a new discussion thread is initiated.

```json
{
  "topic": "thread.created",
  "version": "2.0",
  "timestamp": "2026-07-13T10:00:00.000Z",
  "data": {
    "id": "cth-abc123",
    "entity_type": "CALL",
    "entity_id": "cll-abc123",
    "allo_number": "+14155550100",
    "contact_number": "+14155551234",
    "resolved": false,
    "resolved_at": null,
    "resolved_by": null,
    "comment_count": 1,
    "created_at": "2026-07-13T10:00:00",
    "comment": {
      "id": "thc-abc123",
      "thread_id": "cth-abc123",
      "content": "Can someone call them back today? @[Jane Doe](usr-abc123)",
      "user": {
        "id": "usr-def456",
        "name": "John Smith",
        "email": "john@acme.com"
      },
      "mentions": [
        {
          "user_id": "usr-abc123",
          "name": "Jane Doe"
        }
      ],
      "created_at": "2026-07-13T10:00:00",
      "updated_at": "2026-07-13T10:00:00"
    }
  }
}
```

--------------------------------

### thread.created

Source: https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog

Fired when a discussion thread is started on a conversation item. Includes the thread's first comment and is deduplicated by thread ID.

```APIDOC
## thread.created

### Description
Fired when a discussion thread is started on a conversation item (a call, an SMS, or a conversation note). Includes the thread's first comment.

### Payload Fields
- **id** (string) - Unique thread identifier (cth-*)
- **entity_type** (string) - Type of the item the thread is attached to: CALL, TEXT_MESSAGE, or CONVERSATION_NOTE
- **entity_id** (string or null) - ID of the conversation item (cll-*, msg-*, or not-*)
- **allo_number** (string) - The Allo line the conversation belongs to
- **contact_number** (string) - The contact's phone number
- **resolved** (boolean) - Whether the thread is resolved
- **resolved_at** (string or null) - ISO 8601 timestamp when the thread was resolved
- **resolved_by** (object or null) - User who resolved the thread
- **comment_count** (number) - Number of comments on the thread
- **created_at** (string) - ISO 8601 timestamp when the thread was created
- **comment** (object) - The thread's first comment

### Response Example
{
  "topic": "thread.created",
  "version": "2.0",
  "timestamp": "2026-07-13T10:00:00.000Z",
  "data": {
    "id": "cth-abc123",
    "entity_type": "CALL",
    "entity_id": "cll-abc123",
    "allo_number": "+14155550100",
    "contact_number": "+14155551234",
    "resolved": false,
    "resolved_at": null,
    "resolved_by": null,
    "comment_count": 1,
    "created_at": "2026-07-13T10:00:00",
    "comment": {
      "id": "thc-abc123",
      "thread_id": "cth-abc123",
      "content": "Can someone call them back today? @[Jane Doe](usr-abc123)",
      "user": {
        "id": "usr-def456",
        "name": "John Smith",
        "email": "john@acme.com"
      },
      "mentions": [
        {
          "user_id": "usr-abc123",
          "name": "Jane Doe"
        }
      ],
      "created_at": "2026-07-13T10:00:00",
      "updated_at": "2026-07-13T10:00:00"
    }
  }
}
```

--------------------------------

### thread.comment.created event payload

Source: https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog

Example JSON payload for the thread.comment.created event, which is deduplicated by comment ID.

```json
{
  "topic": "thread.comment.created",
  "version": "2.0",
  "timestamp": "2026-07-13T10:05:00.000Z",
  "data": {
    "id": "thc-def456",
    "thread_id": "cth-abc123",
    "content": "On it.",
    "user": {
      "id": "usr-abc123",
      "name": "Jane Doe",
      "email": "jane@acme.com"
    },
    "mentions": [],
    "created_at": "2026-07-13T10:05:00",
    "updated_at": "2026-07-13T10:05:00"
  }
}
```

--------------------------------

### thread.resolved event payload

Source: https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog

Example JSON payload for the thread.resolved event. Note that this event may be re-delivered and should be deduplicated using the webhook-id header.

```json
{
  "topic": "thread.resolved",
  "version": "2.0",
  "timestamp": "2026-07-13T11:00:00.000Z",
  "data": {
    "id": "cth-abc123",
    "entity_type": "CALL",
    "entity_id": "cll-abc123",
    "allo_number": "+14155550100",
    "contact_number": "+14155551234",
    "resolved": true,
    "resolved_at": "2026-07-13T11:00:00",
    "resolved_by": {
      "id": "usr-def456",
      "name": "John Smith",
      "email": "john@acme.com"
    },
    "comment_count": 2,
    "created_at": "2026-07-13T10:00:00"
  }
}
```

--------------------------------

### call.answered JSON Payload

Source: https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog

Example JSON structure for the call.answered event, containing call metadata and associated contact details.

```json
{
  "topic": "call.answered",
  "version": "2.0",
  "timestamp": "2025-03-15T14:30:08.000Z",
  "data": {
    "from_number": "+33612345678",
    "to_number": "+33112345678",
    "direction": "OUTBOUND",
    "started_at": "2025-03-15T14:30:00.000Z",
    "answered_at": "2025-03-15T14:30:08.000Z",
    "user_email": "john@acme.com",
    "person": {
      "id": "con_5MiGNHp2vI1AN6sTu4Cw",
      "name": "Marie",
      "last_name": "Dupont",
      "email": "marie.dupont@acme.com",
      "emails": ["marie.dupont@acme.com"],
      "numbers": ["+33612345678"],
      "job_title": "Head of Sales"
    },
    "company": {
      "id": "com-a1b2c3d4e5f6",
      "name": "Acme Corp"
    },
    "deals": null
  }
}
```

--------------------------------

### call.received

Source: https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog

The call.received event is triggered when an inbound call starts ringing, before it is answered. It provides context about the caller, including associated contact, company, and deal information if available.

```APIDOC
## call.received

### Description
Fired when an inbound call starts ringing, before the call is answered. When a matching contact is found, the event includes person, company, and deals objects with contact context.

### Payload Fields
- **from_number** (string) - Caller's phone number
- **to_number** (string) - Your Allo phone number
- **started_at** (string) - ISO 8601 timestamp when the call started ringing
- **user_email** (string) - Email of the Allo user assigned to the number
- **person** (object or null) - Matching contact person. Absent if no contact matches the caller's number.
- **company** (object or null) - Company linked to the contact. null if none.
- **deals** (array or null) - Deals linked to the contact. null if none.

### Example Payload
{
  "topic": "call.received",
  "version": "2.0",
  "timestamp": "2025-03-15T14:30:00.000Z",
  "data": {
    "from_number": "+33612345678",
    "to_number": "+33112345678",
    "started_at": "2025-03-15T14:30:00.000Z",
    "user_email": "john@acme.com",
    "person": {
      "id": "con_5MiGNHp2vI1AN6sTu4Cw",
      "name": "Marie",
      "last_name": "Dupont",
      "email": "marie.dupont@acme.com",
      "emails": ["marie.dupont@acme.com"],
      "numbers": ["+33612345678"],
      "job_title": "Head of Sales",
      "linkedin_url": "https://linkedin.com/in/mariedupont",
      "lead_source": "Inbound"
    },
    "company": {
      "id": "com-a1b2c3d4e5f6",
      "name": "Acme Corp"
    },
    "deals": [
      {
        "id": "dea-x1y2z3w4v5u6",
        "name": "Enterprise Plan",
        "status": "qualified",
        "value": 25000.0,
        "currency": "EUR",
        "close_date": "2025-06-15T00:00:00"
      }
    ]
  }
}
```

--------------------------------

### List phone numbers OpenAPI definition

Source: https://help.withallo.com/en/v2/api-reference/phone-numbers/list-numbers

The OpenAPI specification for the GET /v2/api/numbers endpoint, including the response schema and example data.

```yaml
openapi: 3.0.3
info:
  title: Allo API
  description: >-
    Allo API provides programmatic access to your Allo account, allowing you to
    manage webhooks, retrieve calls and contacts, and send SMS messages.


    All requests to `/v1/api/**` endpoints automatically go through quota
    checking and scope validation.
  version: 1.0.0
  contact:
    name: Allo Support
servers:
  - url: https://api.withallo.com
    description: Production server
security: []
tags:
  - name: Summary Templates
    description: >-
      Manage call summary templates that control how AI-generated call summaries
      are structured for your team.
  - name: Webhooks
    description: >-
      Manage webhook endpoints to receive real-time notifications about events
      in your Allo account. Each endpoint subscribes to one or more event topics
      and is verified with a signing secret.
  - name: Calls
    description: >-
      Retrieve and search call records with filtering and pagination. Filter
      calls by your Allo phone number.
  - name: Contacts
    description: >-
      Search and retrieve contact information with sorting and pagination.
      Includes engagement level tracking.
  - name: SMS
    description: Send SMS messages to phone numbers using your Allo numbers.
  - name: Phone Numbers
    description: Retrieve information about your Allo phone numbers.
  - name: Analytics
    description: Pre-computed call metrics, team performance, and outbound dial funnel
  - name: CRM
    description: Manage people, companies, and deals in your CRM.
  - name: Notes
    description: >-
      Internal team notes on conversations and CRM people, with @mention
      support. Notes are never visible to the contact.
  - name: Threads
    description: >-
      Team discussion threads attached to a conversation item (call, SMS, or
      conversation note). One thread per item.
paths:
  /v2/api/numbers:
    get:
      tags:
        - Phone Numbers
      summary: List phone numbers
      description: Returns all phone numbers and sender IDs on your team.
      operationId: listNumbers
      responses:
        '200':
          description: List of phone numbers
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PhoneNumber'
              example:
                data:
                  - number: '+14155550100'
                    name: Sales US
                    country: US
                    type: NUMBER
                    capabilities:
                      - VOICE
                      - SMS
                      - MMS
                    users:
                      - id: usr-abc123
                        name: Adrien
                        email: adrien@company.com
                  - number: '+33612345678'
                    name: Support FR
                    country: FR
                    type: NUMBER
                    capabilities:
                      - VOICE
                    users:
                      - id: usr-abc123
                        name: Adrien
                        email: adrien@company.com
                      - id: usr-def456
                        name: Marie
                        email: marie@company.com
                  - number: null
                    name: Acme Corp
                    country: FR
                    type: SENDER_ID
                    capabilities:
                      - SMS
                    users: []
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '429':
          $ref: '#/components/responses/ApiRateLimited'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    PhoneNumber:
      type: object
      properties:
        number:
          type: string
          nullable: true
          description: Phone number in E.164 format (null for sender IDs)
          example: '+14155550100'
        name:
          type: string
          nullable: true
          description: Display label
          example: Sales US
        country:
          type: string
          nullable: true
          description: ISO country code
          example: US
        type:
          type: string
          enum:
            - NUMBER
            - SENDER_ID
          description: Whether this is a phone number or a sender ID
        capabilities:
          type: array
```

--------------------------------

### Get webhook OpenAPI definition

Source: https://help.withallo.com/en/v2/api-reference/webhooks/get-webhook

The OpenAPI specification for the GET /v2/api/webhooks/{webhook_id} endpoint.

```yaml
openapi: 3.0.3
info:
  title: Allo API
  description: >-
    Allo API provides programmatic access to your Allo account, allowing you to
    manage webhooks, retrieve calls and contacts, and send SMS messages.


    All requests to `/v1/api/**` endpoints automatically go through quota
    checking and scope validation.
  version: 1.0.0
  contact:
    name: Allo Support
servers:
  - url: https://api.withallo.com
    description: Production server
security: []
tags:
  - name: Summary Templates
    description: >-
      Manage call summary templates that control how AI-generated call summaries
      are structured for your team.
  - name: Webhooks
    description: >-
      Manage webhook endpoints to receive real-time notifications about events
      in your Allo account. Each endpoint subscribes to one or more event topics
      and is verified with a signing secret.
  - name: Calls
    description: >-
      Retrieve and search call records with filtering and pagination. Filter
      calls by your Allo phone number.
  - name: Contacts
    description: >-
      Search and retrieve contact information with sorting and pagination.
      Includes engagement level tracking.
  - name: SMS
    description: Send SMS messages to phone numbers using your Allo numbers.
  - name: Phone Numbers
    description: Retrieve information about your Allo phone numbers.
  - name: Analytics
    description: Pre-computed call metrics, team performance, and outbound dial funnel
  - name: CRM
    description: Manage people, companies, and deals in your CRM.
  - name: Notes
    description: >-
      Internal team notes on conversations and CRM people, with @mention
      support. Notes are never visible to the contact.
  - name: Threads
    description: >-
      Team discussion threads attached to a conversation item (call, SMS, or
      conversation note). One thread per item.
paths:
  /v2/api/webhooks/{webhook_id}:
    get:
      tags:
        - Webhooks
      summary: Get webhook
      description: Returns a single webhook endpoint by ID, including its `signing_secret`.
      operationId: getWebhook
      parameters:
        - name: webhook_id
          in: path
          required: true
          description: The webhook endpoint ID (e.g. "ep_2NfDKEm9sF8xK3pQr1Zt").
          schema:
            type: string
            example: ep_2NfDKEm9sF8xK3pQr1Zt
      responses:
        '200':
          description: Webhook endpoint
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/WebhookApiResponse'
              example:
                data:
                  id: ep_2NfDKEm9sF8xK3pQr1Zt
                  url: https://example.com/webhooks/allo
                  topics:
                    - call.received
                    - sms.received
                  description: Production event stream
                  enabled: true
                  signing_secret: whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD
                  created_at: '2026-04-21T14:30:00Z'
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '404':
          $ref: '#/components/responses/ApiNotFound'
        '429':
          $ref: '#/components/responses/ApiRateLimited'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    WebhookApiResponse:
      type: object
      description: A webhook endpoint.
      properties:
        id:
          type: string
          description: Unique webhook endpoint ID.
          example: ep_2NfDKEm9sF8xK3pQr1Zt
        url:
          type: string
          format: uri
          description: HTTPS URL that receives event deliveries.
        topics:
          type: array
          items:
            $ref: '#/components/schemas/WebhookTopic'
          description: Event topics this endpoint is subscribed to.
        description:
          type: string
          nullable: true
          description: Optional human-readable label.
        enabled:
          type: boolean
          description: Whether the endpoint is active.
        signing_secret:
          type: string
          nullable: true
          description: >-
            Secret used to verify delivery signatures. Returned only when the
            webhook is created or fetched by ID.
        created_at:
          type: string
          format: date-time
          nullable: true
          description: When the endpoint was created.
    WebhookTopic:
```

--------------------------------

### Get account OpenAPI definition

Source: https://help.withallo.com/en/v2/api-reference/partner/get-account

The OpenAPI specification for the GET /v2/api/partner/accounts/{id} endpoint.

```yaml
openapi: 3.0.3
info:
  title: Allo API
  description: >-
    Allo API provides programmatic access to your Allo account, allowing you to
    manage webhooks, retrieve calls and contacts, and send SMS messages.


    All requests to `/v1/api/**` endpoints automatically go through quota
    checking and scope validation.
  version: 1.0.0
  contact:
    name: Allo Support
servers:
  - url: https://api.withallo.com
    description: Production server
security: []
tags:
  - name: Summary Templates
    description: >-
      Manage call summary templates that control how AI-generated call summaries
      are structured for your team.
  - name: Webhooks
    description: >-
      Manage webhook endpoints to receive real-time notifications about events
      in your Allo account. Each endpoint subscribes to one or more event topics
      and is verified with a signing secret.
  - name: Calls
    description: >-
      Retrieve and search call records with filtering and pagination. Filter
      calls by your Allo phone number.
  - name: Contacts
    description: >-
      Search and retrieve contact information with sorting and pagination.
      Includes engagement level tracking.
  - name: SMS
    description: Send SMS messages to phone numbers using your Allo numbers.
  - name: Phone Numbers
    description: Retrieve information about your Allo phone numbers.
  - name: Analytics
    description: Pre-computed call metrics, team performance, and outbound dial funnel
  - name: CRM
    description: Manage people, companies, and deals in your CRM.
  - name: Notes
    description: >-
      Internal team notes on conversations and CRM people, with @mention
      support. Notes are never visible to the contact.
  - name: Threads
    description: >-
      Team discussion threads attached to a conversation item (call, SMS, or
      conversation note). One thread per item.
paths:
  /v2/api/partner/accounts/{id}:
    get:
      tags:
        - Partner
      summary: Get account
      description: >-
        Returns the status and activation state of an account you provisioned.
        Requires the `PARTNER` scope.
      operationId: getPartnerAccount
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The account id returned on create.
      responses:
        '200':
          description: Account
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        example: usr_2Nf...
                      api_key:
                        type: string
                        nullable: true
                        description: >-
                          Scoped API key for the new account. Returned only on
                          create.
                        example: b1c2...
                      phone_numbers:
                        type: array
                        items:
                          type: string
                        example:
                          - '+33712345678'
                      status:
                        type: string
                        example: ACTIVE
                      activated:
                        type: boolean
                        description: True once the customer has signed in on a device.
                        example: false
                      partner_client_ref:
                        type: string
                        nullable: true
                        example: crm-12345
        '401':
          $ref: '#/components/responses/ApiUnauthorized'
        '403':
          description: The API key lacks the PARTNER scope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
        '404':
          description: >-
            No account with this id was provisioned by your API key
            (PARTNER_ACCOUNT_NOT_FOUND).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
```

--------------------------------

### Idempotency Request Example

Source: https://help.withallo.com/en/v2/api-reference/guides/error-handling

Demonstrates using an Idempotency-Key header to safely retry a POST request.

```bash
# First request — executes the operation
curl -X POST "https://api.withallo.com/v2/api/conversations/items/cll-abc123/tags" \
  -H "Authorization: Api-Key ak_live_your_key" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"tags": ["qualified"]}'
# → 200 OK, Idempotency-Key: 550e8400-...

# Retry — returns stored response without re-executing
curl -X POST "https://api.withallo.com/v2/api/conversations/items/cll-abc123/tags" \
  -H "Authorization: Api-Key ak_live_your_key" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"tags": ["qualified"]}'
# → 200 OK, Idempotency-Replayed: true
```

--------------------------------

### partner.account.login

Source: https://help.withallo.com/en/v2/api-reference/webhooks/event-catalog

Fired when a reseller-provisioned account signs in on a device for the first time. Delivered to the partner's webhook endpoint.

```APIDOC
## partner.account.login

### Description
Fired when a reseller-provisioned account signs in on a device for the first time — the moment its number goes live. Delivered to the partner's webhook endpoint (not the account's), so resellers can track activation.

### Payload Fields
- **account_id** (string) - The provisioned account's user ID (usr-*)
- **partner_client_ref** (string or null) - Your own reference, set when the account was created
- **email** (string) - The account's email
- **name** (string) - The account's name

### Example Payload
{
  "topic": "partner.account.login",
  "version": "2.0",
  "timestamp": "2025-03-15T18:00:00.000Z",
  "data": {
    "account_id": "usr-160F3A46629692CF6E022E09A6217A4F0AD21B45",
    "partner_client_ref": "client-4271",
    "email": "owner@vibrantevents.com",
    "name": "Vibrant Occasions Event Rentals"
  }
}
```

--------------------------------

### Expose local server with ngrok

Source: https://help.withallo.com/en/v2/api-reference/webhooks/testing

Use this command to create a public HTTPS URL for a local server running on port 3000.

```bash
ngrok http 3000
```

--------------------------------

### POST /v2/api/partner/accounts

Source: https://help.withallo.com/en/v2/api-reference/partner/create-account

Creates an Allo account for one of your customers, provisions a phone number, and returns a scoped API key for the account. Requires the PARTNER scope.

```APIDOC
## POST /v2/api/partner/accounts

### Description
Creates an Allo account for one of your customers, provisions a phone number, and returns a scoped API key for the account. Requires the `PARTNER` scope. The account is billed as one seat on your subscription.

### Method
POST

### Endpoint
/v2/api/partner/accounts

### Request Body
- **email** (string) - Required - Becomes the account's login.
- **name** (string) - Required - The name of the customer.
- **interval** (string) - Required - Billing interval for the account's seat (MONTHLY or YEARLY).
- **number_preference** (object) - Required - Configuration for the phone number to be provisioned.
- **personal_mobile** (string) - Optional - An existing mobile the new number can attach to.
- **partner_client_ref** (string) - Optional - Your own reference for this customer.

### Request Example
{
  "email": "client@example.com",
  "name": "Jane Doe",
  "interval": "MONTHLY",
  "number_preference": {
    "country": "FR"
  },
  "personal_mobile": "+33612345678",
  "partner_client_ref": "crm-12345"
}
```

--------------------------------

### POST /v2/api/partner/accounts

Source: https://help.withallo.com/en/v2/api-reference/partner/overview

Creates a new customer account, provisions a number, and returns a scoped key for the account.

```APIDOC
## POST /v2/api/partner/accounts

### Description
Create an account, provision a number, and return a scoped key.

### Method
POST

### Endpoint
/v2/api/partner/accounts
```
Tokens:
Raw