# Unlisted page

This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

## On this page

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

## Version

This integration utilizes the OutreachREST API **v2**.

## Base URL

The base URL used for all Outreach API endpoints:

```
https://api.outreach.io/api/v2
```

## Authentication & Authorization

The DataGrail Outreach 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 Outreach API endpoints by a third party. DataGrail stores your API credentials encrypted and protected.

### Scopes

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

| Scope | Base | Access | Deletion |
| --- | --- | --- | --- |
| `accounts.read` |  | ✅ |  |
| `calls.read` |  | ✅ |  |
| `callDispositions.read` |  | ✅ |  |
| `callPurposes.read` |  | ✅ |  |
| `complianceRequests.read` |  | ✅ | ✅ |
| `complianceRequests.write` |  |  | ✅ |
| `events.read` |  | ✅ |  |
| `mailboxes.read` |  | ✅ |  |
| `mailings.read` |  | ✅ |  |
| `personas.read` |  | ✅ |  |
| `phoneNumbers.read` |  | ✅ |  |
| `prospects.all` | ✅ | ✅ | ✅ |
| `sequences.read` |  | ✅ |  |
| `sequenceStates.read` |  | ✅ |  |
| `sequenceSteps.read` |  | ✅ |  |
| `sequenceTemplates.read` |  | ✅ |  |
| `snippets.read` |  | ✅ |  |
| `stages.read` |  | ✅ |  |
| `tasks.read` |  | ✅ |  |
| `teams.read` |  | ✅ |  |
| `templates.read` |  | ✅ |  |
| `users.read` |  | ✅ |  |

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 | `/prospects` | Verify connection and access to the requested scopes |  |
| GET | `https://api.outreach.io/oauth/authorize` | Request authorization |  |
| POST | `https://api.outreach.io/oauth/token` | Get and refresh access token |  |

## Limits

Limits in Outreach 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 **Outreach** integration provides **Synchronous** Access capabilities for the following supported identifier category: **Email**.

#### Data Interactions

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

1. Fetch a **Collection of Resources** using the Data Subject email as a filter.
2. For each identified prospect object, extract the following associated objects:
   - account
   - persona
   - stage
   - calls
   - mailings
   - opportunities
   - phone numbers
   - sequence states
   - tasks
3. For **creator**, **owner**, **updater** objects, DataGrail only returns user IDs to protect privacy of internal users.

#### Endpoints Utilized

| Method | Endpoint | Purpose | Docs |
| --- | --- | --- | --- |
| GET | `/accounts/ID` | Get an Account by ID |  |
| GET | `/calls` | Get a Collection of Calls |  |
| GET | `/mailings` | Get a Collection of Mailings |  |
| GET | `/opportunities` | Get a Collection of Opportunities |  |
| GET | `/personas/ID` | Get a Persona by ID |  |
| GET | `/phoneNumbers` | Get a Collection of Phone Numbers |  |
| GET | `/prospects` | Fetch a Collection of Resources |  |
| GET | `/sequenceStates` | Get a Collection of Sequence States |  |
| GET | `/stages/ID` | Get a Stage by ID |  |
| GET | `/tasks` | Get a Collection of Tasks |  |

### Deletion

DataGrail's **Outreach** integration provides **Asynchronous (Whole Record)** Deletion capabilities for the following supported identifier category: **Email**.

#### Data Interactions

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

1. Fetch a **Collection of Resources** using the Data Subject email as a filter.
2. Create a **Compliance Request** for all identified objects.
3. Check the status of the submitted request to confirm deletion.

#### Endpoints Utilized

| Method | Endpoint | Purpose | Docs |
| --- | --- | --- | --- |
| GET | `/complianceRequests` | View the status of the submitted request |  |
| POST | `/complianceRequests` | Create Compliance Requests |  |
| GET | `/prospects` | Fetch a Collection of Resources |  |

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