> 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/start-envelope-signature.md).

# Start Envelope Signature

Initiates the signing process for an envelope, and upon successful initiation, it provides a signing URL that the recipient can use to access the document for signing.

***

## Start Envelope Signature API

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

***

### 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> |

***

#### Path Parameters

| Name                                           | Type | Description                              |
| ---------------------------------------------- | ---- | ---------------------------------------- |
| envelope\_id<mark style="color:red;">\*</mark> | UUID | The envelope ID from Create Envelope API |

***

#### Response Body

#### Start Signature process initiated successfully

HTTP Status Code: `200`

Status : `SUCCESS`

```json
{
    "success": true,
    "data": {
        "envelope_id": "{uuid}",
        "envelope_status": "PENDING",
        "signature_links": [
            {
                "email": "example1@email.com",
                "signature_link": "https://sign.vida.id/signEnvelope/{code}"
            },
            {
                "email": "example2@email.com",
                "signature_link": "https://sign.vida.id/signEnvelope/{code}"
            }
        ]
    }
}
```

#### Bad Request - envelope in completed state

The envelope is already in signed or completed state.

HTTP Status Code: `400`

Status : `ERROR`

```json
{
    "message": "Unable to execute, the envelope is already in signing or completed state.",
    "code": "ER.10113"
}
```

#### Forbidden - Disbaled Direct Sign Feature

The Direct Sign 'send' endpoint is not available for use.

HTTP Status Code: `403`

Status : `ERROR`

```json
{
    "message": "Unable to operate via the integration API.",
    "code": "ES.105011"
}
```

#### Forbidden

Incase when Envelope authorization is forbidden.

HTTP Status Code: `403`

Status : `ERROR`

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

#### Forbidden - Disbale Direct Sign Feature

You cannot use direct sign send endpoint

HTTP Status Code: `403`

Status : `ERROR`

```json
{
    "message": "You’re not allowed to send envelopes from DirectSign.",
    "code": "AS.11001"
}
```

***

## Get Envelope Signature Links

<mark style="color:blue;">`GET`</mark> `/core/external-api/rest/v1/envelope/{envelope_id}/signature-links`

***

#### 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 | \*/\*               |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer Access Token |

***

#### Response Body

#### Signature link requested successfully

HTTP Status Code: `200`

Status : `SUCCESS`

```json
{
    "success": true,
    "data": {
        "envelope_id": "{uuid}",
        "envelope_status": "PENDING",
        "signature_links": [
            {
                "email": "example1@email.com",
                "signature_link": "https://sign.vida.id/signEnvelope/{code}"
            },
            {
                "email": "example2@email.com",
                "signature_link": "https://sign.vida.id/signEnvelope/{code}"
            }
        ]
    }
}
```

#### Bad Request - envelope does not exist

The requested envelope does not exist.

HTTP Status Code: `400`

Status : `ERROR`

```json
{
    "code":"ES.10501",
    "message":"Envelope not found."
}
```

#### Forbidden

Incase when Envelope authorization is forbidden.

HTTP Status Code: `403`

Status : `ERROR`

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