> For the complete documentation index, see [llms.txt](https://docs.vida.id/identity-stack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vida.id/identity-stack/sign/digital-signature/directsign-api/api-reference/recall-envelope.md).

# Recall Envelope

This API enables the option to cancel or retract an envelope before all signatures are completed. When a document is recalled, the recipient will receive a notification & the document is voided.

### API Description

<mark style="color:green;">`POST`</mark> `{environment-url}/core/external-api/rest/v1/envelope/{envelope_id}/recall-signature`

#### Path Parameters

| Name                                           | Type | Description     |
| ---------------------------------------------- | ---- | --------------- |
| envelope\_id<mark style="color:red;">\*</mark> | UUID | The envelope Id |

#### Headers

| Name                                            | Type   | Description                                                                                                                                                               |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json                                                                                                                                                          |
| Authorization<mark style="color:red;">\*</mark> | String | <p>Bearer Access Token<br><br>Get the access token by calling the</p><p><a href="/pages/XOKnwALziwtzopCd8Bb1#api-description"><strong>Authentication</strong></a> API</p> |

#### Request Body

| Name   | Type   | Description                                             |
| ------ | ------ | ------------------------------------------------------- |
| reason | String | The reason for recalling envelope. Length Limit (0-255) |

#### Response Body

#### Recall Envelope Requested Successfully

HTTP Status Code: `200`

Status : `SUCCESS`

Response:

```json
empty content
```

#### Bad Request - invalid recall reason text size&#x20;

HTTP Status Code: `400`

Status : `ERROR`

**JSON Response**

```json
{
    "code":"MG.10303",
    "message":"reason:size must be between 0 and 255."
}
```

#### Bad Request - envelope cannot be recalled

The envelope is in a state which cannot be recalled.

HTTP Status Code: `400`

Status : `ERROR`

**JSON Response**

```json
{
    "code":"MG.10303",
    "message":"The status of the envelope is %s, and cannot be recalled."
}
```

#### Bad Request - envelope is already recalled

HTTP Status Code: `400`

Status : `ERROR`

**JSON Response**

```json
{
    "code":"MG.10502",
    "message":"This envelope is already in recalled status, cannot recall again."
}
```

#### Bad Request - envelope not found

HTTP Status Code: `400`

Status : `ERROR`

**JSON Response**

```json
{
    "code":"ES.10501",
    "message":"The envelope does not exist."
}
```

#### Forbidden

Incase when Envelope authorization is forbidden.

HTTP Status Code: `403`

Status : `ERROR`

**JSON Response**

```json
{
    "message":"Envelope Authorization Forbidden",
    "code":"MG.10379"
}
```