# Myphoner API reference

A small, RESTful JSON API for moving data in and out of Myphoner: users, lists, leads, calls and webhooks.

Base URL: `https://<your_subdomain>.myphoner.com/api/v2`

- [Getting started](#getting-started)
  - [Authentication](#authentication)
  - [Rate limits](#rate-limits)
  - [Conventions](#conventions)
- [Users](#users)
  - [Invite a user](#invite-user)
- [Lists](#lists)
  - [List all lists](#list-lists)
  - [Create a list](#create-list)
  - [Retrieve a list](#get-list)
  - [List the columns of a list](#list-columns)
  - [List the leads in a list](#list-leads)
  - [Retrieve list statistics](#list-stats)
- [Leads](#leads)
  - [Create a lead](#create-lead)
  - [Retrieve a lead](#get-lead)
  - [Update a lead](#update-lead)
  - [Find leads by field](#find-leads)
  - [Search leads](#search-leads)
  - [Mark a lead as winner](#mark-winner)
  - [Mark a lead for call back](#mark-call-back)
  - [Mark a lead as loser](#mark-loser)
  - [Archive a lead](#archive-lead)
  - [Delegate or claim a lead](#delegate-lead)
  - [Move a lead to another list](#migrate-lead)
- [Calls](#calls)
  - [Retrieve a call](#get-call)
- [Webhooks](#webhooks)
  - [Events](#webhook-events)
  - [Subscribe to events on a list](#subscribe-list)
  - [Subscribe to events account-wide](#subscribe-account)
  - [Receive a notification](#receive-notification)
  - [Delete a webhook](#unsubscribe)

## Getting started

### Authentication

Every request carries an API key in the `Authorization` header. The account key is found in Myphoner under Manage, then Configure, then Integrations.

Each user also has a personal API key with the same access rights as that user. It lives on the user's preferences page under Credentials.

```bash
curl https://<your_subdomain>.myphoner.com/api/v2/lists \
  -H "Accept: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
```

> **Treat the key like a password** Anyone who knows your API key can read and change your account through the API. Keep it out of client-side code and public repositories.

### Rate limits

The API allows 60 requests per minute and 300 requests per 5 minutes. Above that the server answers `429 Too Many Requests`.

A 429 response carries a `Ratelimit-Reset` header with the timestamp at which the next request may be made. Wait until at least that time, and back off exponentially if you keep hitting the limit. Clients that ignore 429 responses lose data.

### Conventions

Requests and responses are JSON. Send `Accept: application/json` and `Content-type: application/json` on every request.

Resources link to each other through `location` paths such as `/api/v2/leads/98765`. Prepend your account subdomain to turn a path into a full URL.

The examples on this page use curl and the fictional `demo` subdomain. Replace the subdomain, the key and the ids with your own and they can be pasted straight into a terminal.

Manipulating leads and events through the API does not trigger [webhooks](#webhooks).

## Users

### Invite a user

`POST /api/v2/users`

Creates a user and sends them an invitation. The user counts toward your subscription once they accept.

**Request**

```bash
curl -X POST https://demo.myphoner.com/api/v2/users \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -d '{
    "accept_charge_upon_invitation_acceptance": "1",
    "user": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "listing_ids": ["28885", "29455"]
    }
  }'
```

**Response**

```json
{
  "id": 6941,
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "created_at": "2017-11-08T10:04:27.822Z",
  "updated_at": "2017-11-08T10:04:27.822Z"
}
```

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `accept_charge_upon_invitation_acceptance` | string | yes | Must be `"1"`. Confirms that you understand a new user raises the subscription fee once the invitation is accepted. |
| `user[email]` | string | yes | Email address the invitation is sent to. |
| `user[first_name]` | string | no |  |
| `user[last_name]` | string | no |  |
| `user[agent]` | boolean | no | Give the user the Agent role. Default `true`. |
| `user[users_admin]` | boolean | no | Give the user the User manager role. Default `false`. |
| `user[lists_admin]` | boolean | no | Give the user the Data manager role. Default `false`. |
| `user[analyst]` | boolean | no | Give the user the Analyst role. Default `false`. |
| `user[supervisor]` | boolean | no | Give the user the Supervisor role. Default `false`. |
| `user[listing_ids]` | array of integers | no | Ids of the lists the user can work when they have the Agent role. |

## Lists

### List all lists

`GET /api/v2/lists`

**Request**

```bash
curl https://demo.myphoner.com/api/v2/lists \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
```

**Response**

```json
[
  {
    "id": 15288,
    "name": "Campaign 1",
    "location": "/api/v2/lists/15288",
    "created_at": "2016-11-15T12:36:28.024Z",
    "locked_on_defaults": true,
    "leads_count": 5
  },
  {
    "id": 4146,
    "name": "Campaign 2",
    "location": "/api/v2/lists/4146",
    "created_at": "2015-08-20T11:11:14.394Z",
    "locked_on_defaults": false,
    "leads_count": 5093
  }
]
```

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `locked_on_defaults` | boolean | no | When `true` or `1`, only lists that guarantee the default fields are returned. |

### Create a list

`POST /api/v2/lists`

**Request**

```bash
curl -X POST https://demo.myphoner.com/api/v2/lists \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -d '{
    "list": {
      "name": "New Campaign",
      "columns_attributes": {
        "0": { "label": "Name", "kind": "none" },
        "1": { "label": "Phone", "kind": "phone" }
      }
    }
  }'
```

**Response**

```json
{
  "id": 29999,
  "name": "New Campaign",
  "location": "/api/v2/lists/29999",
  "created_at": "2017-11-08T10:19:19.643Z",
  "locked_on_defaults": false,
  "leads_count": 0,
  "categories": {}
}
```

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `list[name]` | string | yes | Name of the list. |
| `list[columns_attributes]` | object | no | Fields of the list, keyed by position: `{"0": {"label": "Name", "kind": "none"}, "1": {"label": "Phone", "kind": "phone"}}`. Each entry takes `label`, `kind` and optionally `visible`. Fields are ordered by their key. `kind` is one of `none` (text), `phone`, `email`, `url`, `boolean`, `integer`, `date`, `text` (multi-line), `options` or `address`. |
| `list[description]` | string | no | Call script shown to agents while working the list. |
| `list[user_ids]` | array of integers | no | Ids of agents that get access to the list. |
| `list[call_back_categories]` | string | no | Comma-separated sub-categories for call backs. |
| `list[winner_categories]` | string | no | Comma-separated sub-categories for winners. |
| `list[loser_categories]` | string | no | Comma-separated sub-categories for losers. |
| `list[archive_categories]` | string | no | Comma-separated sub-categories for archived leads. |
| `list[skip_categories]` | string | no | Comma-separated sub-categories for skips. |
| `list[prepend_phone]` | boolean | no |  |
| `list[inline_identifiers]` | boolean | no |  |
| `list[show_avatars]` | boolean | no |  |
| `list[lock_on_defaults]` | boolean | no |  |
| `list[queue_new_before_call_backs]` | boolean | no |  |
| `list[queue_new_before_due]` | boolean | no |  |
| `list[duplicates_match_on_phone]` | boolean | no |  |
| `list[duplicates_match_on_email]` | boolean | no |  |
| `list[duplicates_match_on]` | string | no |  |

### Retrieve a list

`GET /api/v2/lists/:id`

**Request**

```bash
curl https://demo.myphoner.com/api/v2/lists/15288 \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
```

**Response**

```json
{
  "id": 15288,
  "name": "Campaign 1",
  "location": "/api/v2/lists/15288",
  "created_at": "2016-11-15T12:36:28.024Z",
  "locked_on_defaults": true,
  "leads_count": 5,
  "categories": {
    "call_back": ["sooner", "later"],
    "winner": ["bigger", "smaller"]
  }
}
```

### List the columns of a list

`GET /api/v2/lists/:id/columns`

Returns the fields of a list. The `key` of each column is the name to use when [creating](#create-lead), [updating](#update-lead) or [finding](#find-leads) leads.

**Request**

```bash
curl https://demo.myphoner.com/api/v2/lists/15288/columns \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
```

**Response**

```json
[
  {
    "id": 188750,
    "key": "first_name",
    "label": "First Name",
    "type": "unicode",
    "input_type": "string",
    "required": false
  },
  {
    "id": 188759,
    "key": "birthday",
    "label": "Birthday",
    "type": "datetime",
    "input_type": "date",
    "required": false
  }
]
```

### List the leads in a list

`GET /api/v2/lists/:id/leads`

Leads are returned newest first by `created_at`, so you can sync your own records by fetching pages until you meet a lead you already know.

**Request**

```bash
curl https://demo.myphoner.com/api/v2/lists/15288/leads \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
```

**Response**

```json
[
  {
    "id": 13722815,
    "location": "/api/v2/leads/13722815",
    "url": "https://demo.myphoner.com/work/leads/13722815",
    "list_name": "Campaign 1",
    "list_location": "/api/v2/lists/15288",
    "primary_identifier": "Craig Tillman",
    "secondary_identifier": "nunc nulla",
    "tertiary_identifier": "mauris erat eget",
    "state": "new",
    "category": null,
    "scheduled_for": null,
    "claimed_by": null,
    "claimed_at": null,
    "detected_duplicates": [],
    "ignored_duplicates": [],
    "created_at": "2016-11-15T12:37:25.331Z",
    "last_updated": "2016-11-15T12:37:25.331Z",
    "lead_data": {
      "first_name": "Craig",
      "last_name": "Tillman",
      "full_name": "Craig Tillman",
      "company_name": "mauris erat eget",
      "title": "nunc nulla",
      "e_mail": "non.justo.Proin@ipsumnunc.ca",
      "mobile_phone": "1 35 195 6007-0909",
      "work_office_phone": "1 57 733 2671-8905",
      "birthday": "1980-06-12 20:10:36"
    }
  }
]
```

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `per_page` | integer | no | Leads per page. Default `50`. |
| `page` | integer | no | Page number. Default `1`. |
| `order` | string | no | Set to `last_updated_first` to sort by `last_updated` descending instead of `created_at`. |

### Retrieve list statistics

`GET /api/v2/lists/:id/stats`

**Request**

```bash
curl https://demo.myphoner.com/api/v2/lists/29455/stats \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
```

**Response**

```json
{
  "id": 29455,
  "name": "5000leads",
  "location": "/api/v2/lists/29455",
  "created_at": "2017-10-26T09:34:00.043Z",
  "locked_on_defaults": false,
  "leads_count": 5099,
  "leads_counts": {
    "new": { "uncategorised": 5060, "total": 5060 },
    "call_back": {
      "bad_time": 1,
      "positive": 3,
      "no_answer": 6,
      "voicemail": 2,
      "gatekeeper": 0,
      "uncategorised": 16,
      "total": 28
    },
    "won": { "uncategorised": 4, "total": 4 },
    "lost": { "uncategorised": 5, "total": 5 },
    "archived": { "uncategorised": 2, "total": 2 },
    "total": 5099
  }
}
```

## Leads

### Create a lead

`POST /api/v2/lists/:id/leads`

Keys in `lead` are the column keys of the list. Fetch them with [list the columns of a list](#list-columns).

**Request**

```bash
curl -X POST https://demo.myphoner.com/api/v2/lists/15288/leads \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -d '{"lead": {"first_name": "John", "last_name": "Doe", "mobile_phone": "12345678"}}'
```

The `detected_duplicates` and `ignored_duplicates` keys hold arrays of lead ids. After uploading an entire new list this information can take up to an hour to settle, depending on the size of the list, because duplicate detection runs in the background. A single lead created through the API has duplicate detection done within a couple of minutes.

### Retrieve a lead

`GET /api/v2/leads/:id`

Returns a lead in the same shape as [list the leads in a list](#list-leads).

**Request**

```bash
curl https://demo.myphoner.com/api/v2/leads/13722811 \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
```

The `detected_duplicates` and `ignored_duplicates` keys hold arrays of lead ids. After uploading an entire new list this information can take up to an hour to settle, depending on the size of the list, because duplicate detection runs in the background. A single lead created through the API has duplicate detection done within a couple of minutes.

### Update a lead

`PATCH /api/v2/leads/:id`

Keys in `lead` are the column keys of the list. Fetch them with [list the columns of a list](#list-columns).

**Request**

```bash
curl -X PATCH https://demo.myphoner.com/api/v2/leads/13722820 \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -d '{"lead": {"full_name": "John Doe", "company_name": "Doe Inc."}}'
```

Responds with `204 No Content` on success.

### Find leads by field

`GET /api/v2/lists/:id/leads/find`

Exact match on one or more fields of the list. By default all supplied fields must match; pass `matchall=false` to match any of them.

**Request**

```bash
curl "https://demo.myphoner.com/api/v2/lists/15288/leads/find?mobile_phone=15324083898652" \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
```

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `<field_key>` | string | no | Value to match. Repeat with different column keys to match on several fields. |
| `matchall` | boolean | no | Set to `false` to combine conditions with OR instead of AND. |

The `detected_duplicates` and `ignored_duplicates` keys hold arrays of lead ids. After uploading an entire new list this information can take up to an hour to settle, depending on the size of the list, because duplicate detection runs in the background. A single lead created through the API has duplicate detection done within a couple of minutes.

### Search leads

`GET /api/v2/leads/search`

Free-text search across lead data and activity logs, like the search field inside Myphoner.

**Request**

```bash
curl "https://demo.myphoner.com/api/v2/leads/search?query=Houston&list_ids=812,4146" \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
```

**Response**

```json
{
  "total": 2,
  "leads": []
}
```

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | The search string. |
| `list_ids` | string | no | Comma-separated list ids to scope the search to. |
| `per_page` | integer | no | Leads per page. Default `50`. |
| `page` | integer | no | Page number. Default `1`. |

The `detected_duplicates` and `ignored_duplicates` keys hold arrays of lead ids. After uploading an entire new list this information can take up to an hour to settle, depending on the size of the list, because duplicate detection runs in the background. A single lead created through the API has duplicate detection done within a couple of minutes.

### Mark a lead as winner

`POST /api/v2/leads/:id/winner`

**Request**

```bash
curl -X POST https://demo.myphoner.com/api/v2/leads/13722820/winner \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -d '{"lead": {"call_back_in": "10", "scheduled_for": "2016-06-04 08:04:55 UTC", "comment": "My comment", "category": ""}}'
```

Responds with `204 No Content` on success.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `call_back_in` | integer | no | Minutes until the scheduled call back. |
| `scheduled_for` | datetime | no | Time of the call back as `YYYY-MM-DD HH:MM:SS UTC`. Takes precedence over `call_back_in` when both are present. See the getting started guide for how a schedule behaves on leads that are not marked for call back. |
| `comment` | string | no | Text inserted as a comment on the winner event. |
| `category` | string | no | Category of the winner event. Must match an existing category exactly, including case. |

All parameters are optional.

### Mark a lead for call back

`POST /api/v2/leads/:id/call_back`

**Request**

```bash
curl -X POST https://demo.myphoner.com/api/v2/leads/13722820/call_back \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -d '{"lead": {"call_back_in": "10", "scheduled_for": "2016-06-04 08:04:55 UTC", "comment": "My comment", "category": ""}}'
```

Responds with `204 No Content` on success.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `call_back_in` | integer | no | Minutes until the scheduled call back. |
| `scheduled_for` | datetime | no | Time of the call back as `YYYY-MM-DD HH:MM:SS UTC`. Takes precedence over `call_back_in` when both are present. See the getting started guide for how a schedule behaves on leads that are not marked for call back. |
| `comment` | string | no | Text inserted as a comment on the call back event. |
| `category` | string | no | Category of the call back event. Must match an existing category exactly, including case. |

All parameters are optional.

### Mark a lead as loser

`POST /api/v2/leads/:id/loser`

**Request**

```bash
curl -X POST https://demo.myphoner.com/api/v2/leads/13722820/loser \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -d '{"lead": {"call_back_in": "10", "scheduled_for": "2016-06-04 08:04:55 UTC", "comment": "My comment", "category": ""}}'
```

Responds with `204 No Content` on success.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `call_back_in` | integer | no | Minutes until the scheduled call back. |
| `scheduled_for` | datetime | no | Time of the call back as `YYYY-MM-DD HH:MM:SS UTC`. Takes precedence over `call_back_in` when both are present. See the getting started guide for how a schedule behaves on leads that are not marked for call back. |
| `comment` | string | no | Text inserted as a comment on the loser event. |
| `category` | string | no | Category of the loser event. Must match an existing category exactly, including case. |

All parameters are optional.

### Archive a lead

`POST /api/v2/leads/:id/archive`

**Request**

```bash
curl -X POST https://demo.myphoner.com/api/v2/leads/13722820/archive \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -d '{"lead": {"call_back_in": "10", "scheduled_for": "2016-06-04 08:04:55 UTC", "comment": "My comment", "category": ""}}'
```

Responds with `204 No Content` on success.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `call_back_in` | integer | no | Minutes until the scheduled call back. |
| `scheduled_for` | datetime | no | Time of the call back as `YYYY-MM-DD HH:MM:SS UTC`. Takes precedence over `call_back_in` when both are present. See the getting started guide for how a schedule behaves on leads that are not marked for call back. |
| `comment` | string | no | Text inserted as a comment on the archive event. |
| `category` | string | no | Category of the archive event. Must match an existing category exactly, including case. |

All parameters are optional.

### Delegate or claim a lead

`PATCH /api/v2/leads/:id/delegate`

**Request**

```bash
curl -X PATCH https://demo.myphoner.com/api/v2/leads/13722820/delegate \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -d '{"lead": {"delegate_to": "1250"}}'
```

Responds with `204 No Content` on success.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `delegate_to` | integer or string | yes | Id or email of the user that should hold the claim on the lead. |

### Move a lead to another list

`PATCH /api/v2/leads/:id/migrate`

**Request**

```bash
curl -X PATCH https://demo.myphoner.com/api/v2/leads/13722820/migrate \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -d '{"lead": {"to_list_id": "15288"}}'
```

Responds with `204 No Content` on success.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `to_list_id` | integer | yes | Id of the destination list. May be the current list, which is useful when you only want to release a claimed lead. |
| `give_back_leads` | string | no | `"1"` releases the lead if it is claimed. `"0"` or omitted leaves the claim as is. |

## Calls

A call is created when an agent dials from Myphoner. Subscribe to the [new_call](#webhook-events) or [new_recording](#webhook-events) webhook to be told when one is available, then fetch it here.

### Retrieve a call

`GET /api/v2/calls/:id`

**Request**

```bash
curl https://demo.myphoner.com/api/v2/calls/12345 \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
```

**Response**

```json
{
  "location": "/api/v2/calls/12345",
  "user_email": "agent@example.com",
  "destination_number": "+447700900123",
  "duration": 11,
  "started_at": "2026-09-16T09:31:41.000Z",
  "caller_id": { "number": "+442079460000", "name": "Sales line" },
  "direction": "outbound",
  "disposition": "voicemail",
  "state": "completed",
  "lead_id": 98765,
  "event_id": 54321,
  "lead": "/api/v2/leads/98765",
  "list": "/api/v2/lists/42",
  "recordings": [
    { "started_at": "2026-09-16T09:31:47.000Z", "url": "https://recordings.example.com/abc.wav" }
  ]
}
```

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| `location` | string | Path of this call. |
| `user_email` | string | Email of the agent who made the call. |
| `destination_number` | string | Number that was dialled. |
| `duration` | integer | Length of the call in seconds. `0` for unanswered and failed attempts. |
| `started_at` | string | When the call started, ISO 8601 in UTC. |
| `caller_id` | object | The outbound caller ID actually used, as `{"number": string or null, "name": string or null}`. This is the number the recipient saw. With Smart CIDs it varies per call. Always present. |
| `direction` | string | One of `outbound`, `inbound`, `transfer`, `local` or `automated`. |
| `disposition` | string or null | One of `busy`, `failed`, `invalid_number`, `normal`, `no_answer`, `temp_unavail` or `voicemail`. `normal` is a connected call the agent ended as a conversation. `voicemail` is set when the agent uses the voicemail hangup or a Voicemail category while connected. `null` until the call has been processed. |
| `state` | string | One of `initiated`, `calling`, `active` or `completed`. |
| `lead_id` | integer or null | Id of the lead this call belongs to. Same lead as the `lead` link. |
| `event_id` | integer or null | Id of the disposition event on the lead that this call belongs to. `null` while the call is not yet linked to a disposition. |
| `lead` | string or null | Path of the lead. |
| `list` | string or null | Path of the list the lead is in. |
| `recordings` | array | Recordings of the call, each with `started_at` and a `url` to the audio file. Empty when the call was not recorded. |

Unanswered and failed attempts are returned too, with `duration` `0` and a `disposition` such as `no_answer` or `busy`.

To attach a lead outcome to a specific call, use `event_id` rather than matching on timestamps.

The `new_call` webhook fires only once a call is linked to a lead. Inbound calls are tracked separately and do not fire `new_call`. A missed inbound callback re-queues the lead and fires the `call_back` webhook instead.

## Webhooks

Subscribe to events such as a new winner, a call back or a finished call and Myphoner sends an HTTP POST to a URL of your choice the moment they happen. The notification tells you where to fetch the full resource.

Webhooks fire on activity inside Myphoner. Changes made through the API do not trigger them.

### Events

The `event` parameter of a subscription takes one of these values.

| Event | Fires when | Scope |
| --- | --- | --- |
| `winner` | The Winner action was used on a lead. | list |
| `loser` | The Loser action was used on a lead. | list |
| `archive` | The Archive action was used on a lead. | list |
| `call_back` | The Call back action was used on a lead. | list |
| `text` | A text message was sent to a lead. | list |
| `inbound_text` | A text message was received from a lead. | list |
| `new_event` | Any new event, including all of the above, except unclaim and migration. | list |
| `new_comment` | A comment was added to a lead, in any state. | list |
| `lead_created` | An agent created a lead. | list |
| `lead_updated` | An agent changed the lead data of a lead. | list |
| `new_call` | A [call](#calls) was completed and linked to a lead. | list, account |
| `new_recording` | A recorded [call](#calls) was completed. | list, account |

### Subscribe to events on a list

`POST /api/v2/lists/:id/webhook`

**Request**

```bash
curl -X POST https://demo.myphoner.com/api/v2/lists/15288/webhook \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -d '{"webhook": {"target_url": "https://yourdomain.com/path/to/endpoint", "event": "winner"}}'
```

Responds with `201 Created` on success.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `webhook[target_url]` | string | yes | URL on your domain that receives the POST described in [receive a notification](#receive-notification). |
| `webhook[event]` | string | yes | One of the [events](#webhook-events). |

The response is the JSON representation of the webhook. Save its `id`; you need it to unsubscribe.

### Subscribe to events account-wide

`POST /api/v2/webhooks`

Only `new_call` and `new_recording` can be subscribed account-wide.

**Request**

```bash
curl -X POST https://demo.myphoner.com/api/v2/webhooks \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"' \
  -d '{"webhook": {"target_url": "https://yourdomain.com/path/to/endpoint", "event": "new_recording"}}'
```

Responds with `201 Created` on success.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `webhook[target_url]` | string | yes | URL on your domain that receives the POST described in [receive a notification](#receive-notification). |
| `webhook[event]` | string | yes | `new_call` or `new_recording`. |

The response is the JSON representation of the webhook. Save its `id`; you need it to unsubscribe.

### Receive a notification

`POST /your/target_url` (sent by Myphoner to your server)

Myphoner sends this request to the `target_url` of the subscription. The body names the resource to fetch, which is a lead for lead events and a [call](#calls) for `new_call` and `new_recording`.

**Request**

```bash
curl -X POST https://yourdomain.com/path/to/endpoint \
  -H "Content-Type: application/json" \
  -d '{"resource_url": "https://demo.myphoner.com/api/v2/leads/13722820"}'
```

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `resource_url` | string | no | URL of the lead or call the event relates to. |

Respond with a `200` status. The body is ignored.

> **Responding to errors** Respond with `410 Gone` when something is permanently wrong and the subscription should be removed. Any other 4xx or 5xx response is treated as temporary and ignored.

### Delete a webhook

`DELETE /api/v2/webhook/:id`

**Request**

```bash
curl -X DELETE https://demo.myphoner.com/api/v2/webhook/1234 \
  -H "Accept: application/json" \
  -H "Content-type: application/json" \
  -H 'Authorization: Token "<your_api_key>"'
```

Responds with `200 OK` on success.

**Parameters**

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | yes | Id of the webhook, returned when you subscribed. |