## Documentation for the DocuSign Integration

This documentation for the DocuSign integration describes the technical capabilities of this integration, including authorization, scopes/permissions, and utilized endpoints. For more information on how to integrate DocuSign, visit our [connection instructions](https://docs.datagrail.io/docs/integrations/connection-instructions/docusign).

## Version

This integration utilizes the DocuSign eSignature REST API **v2.1**.

## Base URL

The base URL used for all DocuSign API endpoints:

```
https://account.docusign.com/restapi/v2.1
```

## Authentication & Authorization

The DataGrail DocuSign integration connects using **OAuth 2.0** with the following credentials: **Client ID** and **Client Secret**.

**Sensitive Credentials**  
Publicly exposing your API credentials can allow unauthorized access to DocuSign API endpoints by a third party. DataGrail stores your API credentials encrypted and protected.

### Scopes

The DocuSign integration requires specific scopes that _must_ be granted in order to function for a given capability.

| Scope | Base | Access | Deletion |
| --- | --- | --- | --- |
| `openid` | ✅ |  |  |
| `impersonation` | ✅ |  |  |
| `extended` | ✅ |  |  |
| `signature` |  | ✅ | ✅ |

**Base Scopes**  
All base scopes must be granted in order to connect the integration with DataGrail. The remaining scopes are only required if enabling those capabilities.

#### Endpoints Utilized

DataGrail uses the following endpoints to authorize and test the connection:

| Method | Endpoint | Purpose | Docs |
| --- | --- | --- | --- |
| GET | `https://account.docusign.com/oauth/auth` | Request authorization |  |
| POST | `https://account.docusign.com/oauth/token` | Get and refresh access token |  |
| GET | `https://account.docusign.com/oauth/userinfo` | Validate credentials |  |

## Limits

Limits in DocuSign are calculated using the leaky bucket algorithm. All requests that are made after rate limits have been exceeded are throttled and an `HTTP 429 Too Many Requests` error is returned. Requests succeed again after enough requests have emptied out of the bucket.

- DataGrail supports requests throttling to stay within 70-80% of specified service rate limits.
- DataGrail processes API responses with HTTP 429 status to interrupt requests, waiting and retrying (using an exponential backoff strategy).

## Capabilities

### Access

DataGrail's **DocuSign** integration provides **Synchronous** Access capabilities for the following supported identifier category: **Email**.

#### Data Interactions

For **Access** requests, DataGrail will take the following actions:

1. Search **account envelopes** containing the data subject email updated in the last 5 years.
2. Filter search to collect **recipients** related to the data subject email data. Drop all other recipients.
3. Fetch all **account contacts**.
4. Filter contact list by **data subject email**.

#### Endpoints Utilized

| Method | Endpoint | Purpose | Docs |
| --- | --- | --- | --- |
| GET | `/accounts/accountId/contacts` | Fetch all account contacts |  |
| GET | `/accounts/accountId/envelopes` | Search account envelopes containing the data subject email updated in the last 5 years |  |

### Deletion

DataGrail's **DocuSign** integration provides **Synchronous** Deletion capabilities for the following supported identifier category: **Email**.

#### Data Interactions

For **Deletion** requests, DataGrail will take the following actions:

1. Delete a **contact** associated with an **account**.
2. Delete a recipient from “draft” or “sent” envelopes. _If the envelope is "In Process" (has been sent and is not completed or voided), recipients that have completed their actions cannot be deleted._

#### Endpoints Utilized

| Method | Endpoint | Purpose | Docs |
| --- | --- | --- | --- |
| DEL | `/accounts/account_id/contacts/contact_id` | Delete a contact associated with an account |  |
| DEL | `/accounts/account_id/envelopes/envelope_id/recipients/recipient_id` | Delete a recipient from “draft” or “sent” envelopes |  |

## Need help?

If you have any questions, please reach out to your dedicated Account Manager or contact us at [support@datagrail.io](mailto:support@datagrail.io).

_Disclaimer: The information contained in this message does not constitute as legal advice. We would advise seeking professional counsel before acting on or interpreting any material._