> For the complete documentation index, see [llms.txt](https://support.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.docstudio.com/admin-panel/webhooks-callbacks/envelope-callbacks-overview/create-a-callback-api.md).

# Create a Callback (API)

To create a new callback record, use the following request:

| **Method** | ***Request URL\****           |
| ---------- | ----------------------------- |
| POST       | /api/v1/envelope/callback/add |

### **Create callback**

| **URL**       |                                                                                                                                |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Method        | POST                                                                                                                           |
| request URL   | /api/v1/envelope/callback/add                                                                                                  |
| **Headers**   |                                                                                                                                |
| content-type  | application/json                                                                                                               |
| authorization | Bearer {token}, where {token} is the authorization token that the user received after successful authorization on the platform |
| mailbox       | UUID of the mailbox to which you configured callbacks                                                                          |

### **REQUEST BODY**

```json
{
  "filter": {
      "label": ["string"],
      "status": ["COMPLETED"],
      "subject": "string",
      "receiveDateFrom": "2023-02-16T12:34:26.606Z",
      "receiveDateTo": "2023-02-16T12:34:26.606Z",
      "expireDateFrom": "2023-02-16T12:34:26.606Z",
      "expireDateTo": "2023-02-16T12:34:26.606Z",
      "template": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
      "sender": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
      "scope": ["inbox"]
  },
  "url": "string",
  "retries": 10,
  "timeout": 60000,
  "successCode": 200,
  "login": "string",
  "password": "string"
}
```

**Request body parameters are described below:**

<table data-header-hidden><thead><tr><th width="169"></th><th></th></tr></thead><tbody><tr><td>filter *</td><td>It is an object with a filter that determines which callbacks will be triggered. <code>It can be empty if you do not want to use any filters.</code></td></tr><tr><td>label</td><td>Filter envelopes by a label assigned to the envelope</td></tr><tr><td>status</td><td>Filter envelopes by status. Allowed statuses for callbacks are WAITING, COMPLETED, CANCELLED, EXPIRED (case insensitive)</td></tr><tr><td>subject</td><td>Filter envelopes by the respective subject of the envelope. The filter works according to the content rule. This means that if you apply a filter by subject <code>agreement</code>, all envelopes with the word <code>agreement</code> will be added to the callback queue, and a callback will be sent.</td></tr><tr><td>receiveDateFrom</td><td>Filter envelopes by receive date FROM the specified date and time</td></tr><tr><td>receiveDateTo</td><td>Filter envelopes by receive date TO the specified date and time</td></tr><tr><td>expireDateFrom</td><td>Filter envelopes by envelope expiration date FROM the specified date and time</td></tr><tr><td>expireDateTo</td><td>Filter envelopes by envelope expiration date TO the specified date and time</td></tr><tr><td>template</td><td>Filter envelopes by a specific template (the template from which the envelope was created). Allowed values are template UUIDs</td></tr><tr><td>sender</td><td>Filter envelopes by envelope sender. Allowed values are the sender's UUID</td></tr><tr><td>scope</td><td>Filter envelopes by direction of the email. Allowed values are inbox and outbox (case insensitive)</td></tr><tr><td>url *</td><td>The parameter defines the URL where the callback will be sent</td></tr><tr><td>retries *</td><td>The parameter defines the number of callback retry attempts. Retries may be applied if the URL is unreachable or if the success code received from the URL is different from the expected one. Allowed values are from 0 to 10. If <code>0</code> is set in the callback, the system tries to send the callback once and does not retry.</td></tr><tr><td>timeout *</td><td>The parameter defines a timeout in milliseconds for which the system waits for a response with a success code. If the timeout is reached, the retry procedure starts, if configured. Allowed values are from 100 to 60000.</td></tr><tr><td>successCode</td><td>The parameter defines the status code that the system expects for a successfully sent callback. If the status code received from the URL is different from the required one, the retry procedure is initiated, if configured. <code>If no value is set, the default value (Status code: 200) is applied.</code></td></tr><tr><td>login</td><td>The parameter defines the login for Basic auth <code>(if the URL is reachable only with Basic auth, this parameter has to be defined)</code></td></tr><tr><td>password</td><td>The parameter defines the password for Basic auth <code>(if the URL is reachable only with Basic auth, this parameter has to be defined)</code></td></tr></tbody></table>

\* - defines attribute as required

**RESPONSE**

In response, you get a `201` status code in case of successful callback creation and JSON data of the callback.

**Response example (JSON):**

```json
{
  "id": "f8c97405-9185-4998-a3c0-2c4d0edaf43b",
  "filter": {
      "label": ["string"],
      "status": ["COMPLETED"],
      "subject": "string",
      "receiveDateFrom": null,
      "receiveDateTo": null,
      "expireDateFrom": null,
      "expireDateTo": null,
      "template": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
      "sender": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
      "scope": ["inbox"]
  },
  "url": "string",
  "retries": 10,
  "timeout": 60000,
  "successCode": 200,
  "authType": "BASIC"
}
```