Welcome to the Outreach API documentation website! Our platform API is built from the ground up to serve the complex needs of both our internal client applications and our customers and integration partners alike. Our API is based on REST principles and implements the JSON API 1.0 specification. All requests must be authenticated via the OAuth 2.0 protocol, and their authorization scope can be limited on a per-application, per-token basis. See Getting Started for more information.

The Outreach API — via the JSON API specification — supports fetching, creating, updating and deleting resources, and in Making Requests we describe the specific requirements for completing those requests. In addition, we describe how you can use complex query parameters to filter, sort and paginate collections of resources, as well as request included resources and sparse fieldsets.

In Common Patterns we outline important requests and the resources and relationships they require. Our API works great as a lightweight CRM, as an entry-point into our platform’s advanced automation capabilities, and as a tool to collect platform statistics.

Finally, in the API Reference section we describe all of the resources that we support along with the request methods that they expose. Each resource section also contains detailed attribute and relationship information and an example request and response for each action.

To request API access, please visit our Platform marketing page and click “Get Started”. If you have any additional questions, feedback or bug reports, please contact platform@outreach.io.

Getting Started

Authentication

Outreach is continually working to improve our security. Starting on January 1, 2021, all authentication tokens issued by Outreach will be short lived. In addition, effective immediately, all tokens older than 1.5 years are being deleted. See the token availability section for more details. If experiencing issues making API calls to Outreach API, please consider generating a new refresh token or contact platform@outreach.io.

Outreach API applications use the standard OAuth 2.0 authentication flow. Conceptually, this means that any application request will be using two distinct sets of credentials: The API key and secret that identify the application, and the username and password (or SSO access token) that identify the user. An application should never require that users enter an API key or secret of their own.

All Outreach API requests must be authenticated with a token in the request’s HTTP Authorization header. If you have not yet setup an Outreach OAuth application, please contact platform@outreach.io for assistance. Once setup, you can acquire an access token in two steps. First, request an authorization code from an Outreach customer by redirecting them to the following URL:

https://api.outreach.io/oauth/authorize?client_id=<Application_Identifier>&redirect_uri=<Application_Redirect_URI>&response_type=code&scope=<Scope1+Scope2+Scope3>

Note that scope must be a space-separated list of permitted API scopes, and both redirect_uri and scope must be properly URL-encoded. For more information on available OAuth scopes, see the Authorization section in this document.

If you would like to maintain state across the authorization flow, you may optionally include a state parameter, which will be included as part of the redirect URI’s query parameters.

Once the Outreach customer has clicked Authorize they will be redirected back to your link’s redirect_uri with a code query parameter. That code is a short-lived authorization token, and you can exchange that code for an access token, which can then be used to make API requests on behalf of the customer. To receive an access token, make a POST request to the following URL with the following parameters:

Request

curl https://api.outreach.io/oauth/token \
  -X POST \
  -d client_id=<Application_Identifier> \
  -d client_secret=<Application_Secret> \
  -d redirect_uri=<Application_Redirect_URI> \
  -d grant_type=authorization_code \
  -d code=<Authorization_Code>

Response

{
  "access_token": <Access_Token>,
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": <Refresh_Token>,
  "scope": <Scope1+Scope2+Scope3>,
  "created_at": 1503301100
}

A successful response to this request will return a JSON payload including the access_token, a refresh_token and an expires_in timestamp. The access token can be used to make authenticated requests on behalf of the customer, but will expire once the expires_in attribute has passed. (Tokens are also revoked when the customer revokes their authorization grant.) Once the access token has expired, you can retrieve a new one by using the refresh_token grant type and by passing the refresh token to the code parameter:

Note that your application can only retrieve an access token for a user once every 60 seconds. If you attempt to retrieve new access tokens more frequently we may return 429 error responses. Please store the access token and only fetch a new one when it is about to expire.

Request

curl https://api.outreach.io/oauth/token \
  -X POST \
  -d client_id=<Application_Identifier> \
  -d client_secret=<Application_Secret> \
  -d redirect_uri=<Application_Redirect_URI> \
  -d grant_type=refresh_token \
  -d refresh_token=<Refresh_Token>

Response

{
  "access_token": <Access_Token>,
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": <Refresh_Token>,
  "scope": <Scope1+Scope2+Scope3>,
  "created_at": 1503308300
}

You can now make authenticated API requests by including an HTTP Authorization header:

curl https://api.outreach.io/api/v2 \
  -H "Authorization: Bearer <Access_Token>" \
  -H "Content-Type: application/vnd.api+json"

The root API endpoint will return information about your current OAuth application and token, as well as attributes related to your organization.

Token Availability

Effective on January 1, 2021, each user/application pair is able to generate a maximum of 100 access refresh tokens at any given time.

• Access tokens remain active for 2 hours (effective immediately)
• Refresh tokens remain active for 14 days (effective January 1, 2021) To automate the API authentication, use the refresh tokens to sustain the session at runtime.

Please refer to the best practices outlined below for refresh tokens:

• Treat refresh tokens as short-lived tokens. They are not meant to be long lasting.
• A new refresh token is issued with each new access token. Always use the most recent refresh token when requesting a new access token.
• Do not persist your refresh tokens after it has been replaced by a newer refresh token.
• Do not create more access tokens than you need. Continue to re-use your access token until it expires (2 hours).
• Try not to use your refresh token more than once.
• For more information about best practices, please see here.

Authorization

Authorization scopes let you specify exactly what type and level of access your application requires. Your OAuth application’s scopes describe the possible set of values that may be requested, but the specific scopes requested during the authentication process are what will be applied to the resulting access token and used to restrict and permit application access.

Scopes are period-separated strings containing two parts: the first part is a pluralized resource name (e.g. prospects); the second part is a token — read, write, delete or all — that describes the level of access permitted. For example, the scopes prospects.read and prospects.all would both grant access to read prospects, while only the latter would permit write and delete access. Scopes are not additive; the prospects.write scope does not grant read access.

If a customer does not have the required OAuth scope to perform a request, a 403 HTTP response with a descriptive JSON error message will be returned:

{
  "errors": [{
    "id": "unauthorizedOauthScope",
    "title": "Unauthorized OAuth Scope",
    "detail": "Your authorization does not include the required scope 'prospects.read'."
  }]
}

OAuth scopes act as the front gate to our API. Just because a customer possesses the required OAuth scope does not grant them authorization to perform those actions on all resources. For example, many customers may have governance settings that only permit them to manage their own prospects, even though they need the OAuth scope prospects.all to fully manage those owned prospects.

If a customer does not have the required governance permissions to perform a request, a 403 HTTP response with a descriptive error message will be returned:

{
  "errors": [{
    "id": "unauthorizedRequest",
    "title": "Unauthorized Request",
    "detail": "You are not authorized to perform that request."
  }]
}

Maintenance

If the Outreach API must be taken offline for maintenance, all requests will receive a 503 HTTP response with a descriptive JSON error message. The response will also include a ISO-8601-formatted timestamp in its Retry-After header indicating when maintenance is expected to complete. When possible all maintenance windows will be announced at https://status.outreach.io.

{
  "errors": [{
    "id": "scheduledServerMaintenance",
    "title": "Scheduled Server Maintenance",
    "detail": "Scheduled server maintenance is under way; please try again at 2017-01-01T00:00:00"
  }]
}

Rate Limiting

The Outreach API is rate-limited on a per-user basis, with a fixed limit of 10,000 requests per one-hour period. All responses include three rate-limiting headers: the X-RateLimit-Limit header indicates the maximum number of requests permitted per time period; the X-RateLimit-Remaining header indicates how many remaining requests are permitted within the current time period; and the X-RateLimit-Reset header (alias as the Retry-After header) indicates when the rate limit counter will reset. If the rate limit is exceeded, requests will receive a 429 HTTP response with a descriptive JSON error message.

{
  "errors": [{
    "id": "rateLimitExceeded",
    "title": "Rate Limit Exceeded",
    "detail": "You have exceeded your permitted rate limit of 10,000; please try again at 2017-01-01T00:00:00."
  }]
}

Making Requests

Content Negotiation

The Outreach API implements the JSON API 1.0 specification. All requests must specify the JSON API media type (application/vnd.api+json) within the Content-Type request header. Requests failing to specify this content type will receive a 415 HTTP response with a descriptive error message:

{
  "errors": [{
    "id": "unsupportedMediaType",
    "title": "Unsupported Media Type",
    "details": "Expected Content-Type header to be 'application/vnd.api+json'."
  }]
}

For more information, see JSON API content negotiation.

Fetch a Collection of Resources

To fetch a collection of resources, make a GET request against a resource’s pluralized type. The body of the response will be a JSON payload. If the request was successful, the response will contain a top-level data property; otherwise, the response will contain a top-level errors property containing a list of error reasons. See Error Responses for more details.

Request

GET https://api.outreach.io/api/v2/prospects

Request

{
  "data": [{
    "type": "prospect",
    "id": 1,
    "attributes": {
      "firstName": "Sally",
      "lastName": null,
      ...
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": 1
        }
      },
      "mailings": {
        "links": {
          "related": "https://api.outreach.io/api/v2/mailings?filter[prospect][id]=1"
        }
      },
      ...
    }
  },
  ...]
}

In this case of fetching a collection of resources, the data property will be a list of up to 50 resource objects. A resource object is a JSON object that contains at minimum the type and id values of the resource, but may also contain properties for the resource’s attributes and relationships, as well as meta data.

This resource object contains two types of relationship information. The account relationship contains a data property with type and id values. When we reference just a resource’s type and ID, we call the object a resource identifier. The mailings relationship, however, does not contain a data property. Instead, it provides a links property with a related URL that references the list of mailings associated with this prospect. Relationship objects may contain data, links or meta properties.

For more information, see Fetching Resources in the JSON API specification.

Filter and Sort

Oftentimes we want to return just a specific subset of a resource collection. The Outreach API provides two query parameters for specifying collections:

• filter
• sort

Filter parameters restrict collections by certain key-value combinations; the sort parameter orders collections by attributes and relationships’ attributes; See the following examples for more details.

Note that not all attributes permit filter and sort criteria. Please consult the API Reference for more details.

Filter by exact attribute

GET https://api.outreach.io/api/v2/prospects?filter[firstName]=Sally

Filter by exact relationship’s attribute

Update (May, 2023): In order to maintain the performance and reliability of our API services and allow modernization of our service architecture, Outreach has decided to deprecate support for filtering by some of the relationship’s attributes.

Please consult the reference documentation for each relationship to see whether you can use filters like filter[relationship_abc][attribute_1]=Acme, or only filter[relationship_abc][id]=1 is allowed. In the latter case you need to do two requests, first get a list of relationship IDs querying /api/v2/model_abc?filter[name]=Acme and then pass them to the original query as filter[relationship_abc][id]=1,2,3.

GET https://api.outreach.io/api/v2/prospects?filter[account][name]=Acme // deprecated

GET https://api.outreach.io/api/v2/account?filter[name]=Acme
GET https://api.outreach.io/api/v2/prospects?filter[account][id]=1,2,3,5,8,13

Filter by exact attribute and relationship’s attribute

GET https://api.outreach.io/api/v2/prospects?filter[firstName]=Sally&filter[account][name]=Acme

Filter by a list of values

GET https://api.outreach.io/api/v2/prospects?filter[id]=1,2,3,5,8,13

Filter by range of values

GET https://api.outreach.io/api/v2/prospects?filter[id]=5..10

Filter by a less-than-or-equal-to condition

GET https://api.outreach.io/api/v2/prospects?filter[updatedAt]=neginf..2017-01-01

Filter by greater-than-or-equal-to condition

GET https://api.outreach.io/api/v2/prospects?filter[updatedAt]=2017-01-01..inf

Sort by ascending attribute

GET https://api.outreach.io/api/v2/prospects?sort=firstName

Sort by descending attribute

GET https://api.outreach.io/api/v2/prospects?sort=-firstName

Sort by relationship’s attribute

Update (May, 2023): In order to maintain the performance and reliability of our API services and allow modernization of our service architecture, Outreach has decided to deprecate support for sorting by the relationship’s attributes.

Please fetch the result of your query with the relationship’s attribute included and apply sorting locally in your service.

GET https://api.outreach.io/api/v2/prospects?sort=account.name // deprecated

Sort by multiple criteria

GET https://api.outreach.io/api/v2/prospects?sort=lastName,-firstName

New filter syntax

We have added a new parameter, newFilterSyntax=true, that you can use when you need to match values that contain the comma character (,) or two dots (..). This was not possible with the old syntax as the comma character and the two dots had special meaning.

Instead of separating the values with commas, you now use brackets to list an array of values. This means you can use a literal comma in the value. Example:

# old syntax:
GET https://api.outreach.io/api/v2/prospects?filter[firstName]=Sally,Katie

# new syntax:
GET https://api.outreach.io/api/v2/prospects?newFilterSyntax=true&filter[firstName][]=Sally&filter[firstName][]=Katie

# old syntax (does not return the desired result, filters for accounts named "Company" and " Inc"):
GET https://api.outreach.io/api/v2/accounts?filter[name]=Company,%20Inc

# new syntax (filters for "Company, Inc"):
GET https://api.outreach.io/api/v2/accounts?newFilterSyntax=true&filter[name][]=Company,%20Inc

Instead of specifying a range with two dots, you instead use [gte] and [lte] (gte is short for greater-than-or-equal-to, and lte is short for less-than-or-equal-to). So instead of 5..10 you use [gte]=5 and [lte]=10. This means you can use two dots when filtering for values. Instead of neginf and inf, simply leave out either [gte] or [lte] instead. Example:

# old syntax:
GET https://api.outreach.io/api/v2/prospects?filter[id]=5..10

# new syntax:
GET https://api.outreach.io/api/v2/prospects?newFilterSyntax=true&filter[id][gte]=5&filter[id][lte]=10

# old syntax:
GET https://api.outreach.io/api/v2/prospects?filter[updatedAt]=neginf..2017-01-01

# new syntax:
GET https://api.outreach.io/api/v2/prospects?newFilterSyntax=true&filter[updatedAt][lte]=2017-01-01

Pagination

If after using sort and filter you need to further reduce the number of returned entries, you can use pagination. The Outreach API provides page query parameter for this purpose. Page size/limit and offset parameters limit views into large collections. See the following examples for more details.

Cursor-based Pagination

Cursor-based pagination works by returning a pointer to a specific item in the dataset.

GET https://api.outreach.io/api/v2/prospects?page[size]=50&count=false

Along with the first 50 entries, the response contains a top-level links property with first, prev and next links that allow efficient pagination. Using it with the count=false flag is recommended to improve performance of the query.

{
  "data": [
    //...
  ],
  "links": {
    "first": "https://api.outreach.io/api/v2/prospects?page[size]=50",
    "prev": "https://api.outreach.io/api/v2/prospects?page[size]=50&page[before]=eyJjbiI6IkFwaVYyOjpQcm9zcGVjdHNDb250cm9sbGVyIiwic3AiOm51bGwsInN2IjpbXSwiaWQiOjEzNiwidiI6MX0",
    "next": "https://api.outreach.io/api/v2/prospects?page[size]=50&page[after]=eyJjbiI6IkFwaVYyOjpQcm9zcGVjdHNDb250cm9sbGVyIiwic3AiOm51bGwsInN2IjpbXSwiaWQiOjIyNSwidiI6MX0"
  },
}

Offset Pagination (Deprecated)

Please use the cursor-based pagination described above and the top-level links property to advance to next page.

To offset the page start:

GET https://api.outreach.io/api/v2/prospects?page[offset]=50

Note that large offsets on large collections can cause a significant performance hit. For this reason we enforce a maximum offset of 10,000. To work around this limitation, consider using more specific filter criteria or paging across ranges of IDs.

To limit the page size:

GET https://api.outreach.io/api/v2/prospects?page[limit]=3

Note that page limits must not be larger than 1000.

In addition, each collection response will include a top-level links property that will contain first, prev, next and last keys, if applicable. Use these links to easily navigate between slices of a collection.

Request

GET https://api.outreach.io/api/v2/prospects?page[offset]=150

Response

{
  "data": [
    //...
  ],
  "links": {
    "first": "https://api.outreach.io/api/v2/prospects?page[limit]=50&page[offset]=0",
    "prev": "https://api.outreach.io/api/v2/prospects?page[limit]=50&page[offset]=100",
    "next": "https://api.outreach.io/api/v2/prospects?page[limit]=50&page[offset]=200",
    "last": "https://api.outreach.io/api/v2/prospects?page[limit]=50&page[offset]=850"
  }
}

Fetch an Individual Resource

You can fetch individual resources by making a GET request against any particular resource’s pluralized type and ID combination. For example, to retrieve an individual prospect resource:

GET https://api.outreach.io/api/v2/prospects/1

The response format will be the same as when fetching collections except that the data property will contain only the found resource object instead of a list of resource objects.

If a resource could not be found, the request will receive a 404 HTTP response with a descriptive JSON error message:

{
  "errors": [{
    "id": "resourceNotFound",
    "title": "Resource Not Found",
    "detail": "Could not find 'prospect' with ID '1'."
  }]
}

For more information, see Fetching Resources in the JSON API specification.

Include Related Resources

Sometimes when you retrieve a resource you want more than just a reference to its relationships, you want the full details of those relationships, too. With the Outreach API, you can easily specify which relationships to fully include within the request. Specify included resources in the include query parameter; separate multiple resources by commas and relationship-attribute pairs by periods.

For example, to retrieve not just a individual prospect, but also its related stage and account, as well as its account’s owner:

Request

GET https://api.outreach.io/api/v2/prospects/1?include=account.owner,stage

Response

{
  "data": {
    "type": "prospect",
    "id": 1,
    "attributes": {
      "firstName": "Sally",
      "lastName": null,
      ...
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": 1
        }
      },
      "stage": {
        "data": {
          "type": "stage",
          "id": 1
        }
      },
      ...
    }
  },
  "included": [{
    "type": "account",
    "id": 1,
    "attributes": {
      "domain": "www.acme.example.com",
      "name": "Acme",
      ...
    },
    "relationships": {
      ...
    }
  }, {
    "type": "stage",
    "id": 1,
    "attributes": {
      "name": "Initial",
      "order": 1,
      ...
    },
    "relationships": {
      ...
    }
  }, {
    "type": "user",
    "id": 1,
    "attributes": {
      "email": "test-user@example.com",
      ...
    },
    "relationships": {
      ...
    }
  }]
}

Keeping the primary data separate from the list of included resources provides a better separation of concerns, and the final resource tree can be composed by referencing the included resource objects with the resource identifiers within relationships properties.

For more information, see Inclusion of Related Resources in the JSON API specification.

Specify Sparse Fieldsets

By default, resource objects return all of their public attributes and relationships. But sometimes you’re only interested in a few specific fields. In these cases you can specify sparse fieldsets by utilitizing the fields query parameter.

For example, to select only the prospect’s first and last name, as well as the name of the account and stage:

Request

GET https://api.outreach.io/api/v2/prospects/1?include=account,stage&fields[account]=name&fields[prospect]=firstName,lastName&fields[stage]=name

Response

{
  "data": {
    "type": "prospect",
    "id": 1,
    "attributes": {
      "firstName": "Sally",
      "lastName": null
    }
  },
  "included": [
    {
      "type": "account",
      "id": 1,
      "attributes": {
        "name": "Acme"
      },
    },
    {
      "type": "stage",
      "id": 1,
      "attributes": {
        "name": "Initial"
      },
    }
  ]
}

To request data about a relationship whose type does not match the relationship name (e.g. owner is of type user for prospects), you will need to specify the resource type for sparse fieldsets.

Request

GET https://api.outreach.io/api/v2/prospects/1?include=owner&fields[user]=firstName,lastName&fields[prospect]=firstName,lastName

Response

{
  "data": {
    "type": "prospect",
    "id": 1,
    "attributes": {
      "firstName": "Sally",
      "lastName": null
    }
  },
  "included": [
    {
      "type": "user",
      "id": 1,
      "attributes" {
        "firstName": "Amelia",
        "lastName": "Estevez"
      }
    }
  ]
}

For more information, see Sparse Fieldsets in the JSON API specification.

Create a New Resource

You can create a new resource by making a POST request against the resource’s collection path. The request body must contain a JSON payload with a resource object as the primary data. Note that unlike in other circumstances, this resource object must not contain an id property.

For example, to create a new prospect resource with a first name and to associated the new prospect with an existing account:

Request

POST https://api.outreach.io/api/v2/prospects

{
  "data": {
    "type": "prospect",
    "attributes": {
      "firstName": "John"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": 1
        }
      }
    }
  }
}

Response

{
  "data": {
    "type": "prospect",
    "id": 2,
    "attributes": {
      "firstName": "John",
      "lastName": null,
      ...
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": 1
        }
      },
      ...
    }
  }
}

If the request was successful, the request will receive a 201 HTTP response with the same response body that you would retrieve should you fetch the newly created resource again via its permanent URL.

If there was a validation error and the request could not be completed, then the request will receive a 422 HTTP response with a descriptive JSON error message:

{
  "errors": [{
    "id": "validationError",
    "title": "Validation Error",
    "detail": "Name can't be blank.",
    "source": { "pointer": "/data/attributes/name" }
  }]
}

For more information, see Creating Resources in the JSON API specification.

Update (May, 2023): In order to maintain the performance and reliability of our API services and allow modernization of our service architecture, Outreach has decided to remove support for including related objects on create/update operations.

Note that you can specify sparse fieldsets for create actions just like you can when fetching resources. However, if you want to include related objects you need an additional GET request.

Update an Existing Resource

You can update an existing resource by making a PATCH request to the resource’s path. The request body must contain a JSON payload with a resource object as the primary data, and only present fields will be updated. The resource object’s type and id fields must be present and its ID must match the ID within the URL.

For example, to update an existing prospect with a new first name and to remove the account relationship:

PATCH https://api.outreach.io/api/v2/prospects/1

{
  "data": {
    "type": "prospect",
    "id": 1,
    "attributes": {
      "firstName": "Sal"
    },
    "relationships": {
      "account": {
        "data": null
      }
    }
  }
}

If the request was successful, the request will receive a 200 HTTP response with the same response body that you would retrieve should you fetch the newly updated resource again via its permanent URL. If there was a validation error and the request could not be completed, then the request will receive a 422 HTTP response with a descriptive JSON error message.

For more information, see Updating Resources in the JSON API specification.

Update (May, 2023): In order to maintain the performance and reliability of our API services and allow modernization of our service architecture, Outreach has decided to remove support for including related objects on create/update operations.

Note that you can specify sparse fieldsets for create actions just like you can when fetching resources. However, if you want to include related objects you need an additional GET request.

Delete an Existing Resource

You can remove a resource by making a DELETE request to the resource’s path:

DELETE https://api.outreach.io/api/v2/prospects/1

If the request was successful, the request will receive a 204 HTTP response with an empty response body. If there was a validation error and the request could not be completed, then the request will receive a 422 HTTP response with a descriptive JSON error message.

For more information, see Deleting Resources in the JSON API specification.

Other Actions on a Resource

Certain resources have further actions defined for individual items. These are accessed by making a request to a path like:

POST https://api.outreach.io/api/v2/tasks/1/actions/snooze

If the request is successful, the request will receive a 200 HTTP response with the body being the resource’s response body as if you had performed a GET for that resource. If there was an error of some kind in performing the action, you will receive a 422 HTTP response with a descriptive JSON error message.

Some action requests have optional query parameters and/or required query parameters that influence how the action is performed:

POST https://api.outreach.io/api/v2/tasks/1/actions/markComplete?actionParams[completionNote]=I+completed+this

Providing additional, unacceptable parameters will result in a 400 HTTP response being returned.

Error Responses

When an error occurs, the response body’s JSON payload will contain an errors property list instead of a data section. Each error object will contain a unique id and title, as well as specific details about this particular occurence of the error. Errors referencing specific fields will include a JSON source pointer.

For more information, see Error Objects in the JSON API specification.

Common Patterns

The Outreach API’s flexibility helps support a wide range of possibilities and use cases. Our API works great as a light-weight CRM, as an entry-point into our platform’s advanced automation capabilities, and as a tool to collect platform statistics. Continue reading for more specific use cases, and at the end of this section you’ll find a reference to each resource that our API supports, including detailed information about that resource’s attributes, relationships and available links.

Manage Prospects and Accounts

Prospects — and the accounts they are associated with — are two of the core Outreach platform resources, and working with them is easy.

Let’s say you’ve identified a new account that you want to target. You’ve found a few promising leads within that account and you’d like to add them to Outreach. Because you can’t write to an account’s prospects relationship, you’ll want to first create the account resource. Then, with each new prospect that you add you can specify this new account within the prospect’s account relationship.

Note: In general, we’re more likely to permit you to write to a “to-one” relationship (such as the prospect’s account) than we are to a “to-many” (such as the account’s prospects). This choice is made for both technical and conceptual reasons, and it’s something to lookout for. Consult the API Reference for details on specific resources.

To add a new account:

Request

POST https://api.outreach.io/api/v2/accounts

{
  "data": {
    "type": "account",
    "attributes": {
      "name": "Acme"
    }
  }
}

Note: The requests in this section omit the necessary headers for brevity, namely Authorization and Content-Type; they are necessary when performing actual requests. Additionally the JSON data for the request body is simply described below the request line; actual request must include this data as the request body.

If the request was successful, the newly created account resource will be returned:

Response

{
  "data": {
    "type": "account",
    "id": 1,
    "attributes": {
      "createdAt": "2017-01-01T00:00:00",
      "name": "Acme",
      "updatedAt": "2017-01-01T00:00:00",
      ...
    },
    "relationships": {
      "prospects": {
        "links": {
          "related": "https://api.outreach.io/api/v2/prospects?filter[account][id]=1"
        }
      },
      ...
    }
  }
}

Note that null attributes and relationships have been removed for brevity. By default resource objects include all attributes and relationships regardless of their value.

You can see from this response that Outreach has added a bit more information than you provided. First, the fields createdAt and updatedAt have been added with timestamps equal to when the request was made. Outreach maintains these timestamps internally for almost all resources; while they are visible, you cannot write to them. Second, a relationships section has been added. The account resource exposes a single relationship, prospects. Because accounts often contain many prospects, we only expose a related link and not a data list of resource identifiers. If you visit this URL you would receive an empty response, because we have not yet added any prospects to this account. Let’s do that now!

To add a new prospect to an account:

Request

POST https://api.outreach.io/api/v2/prospects

{
  "data": {
    "type": "prospect",
    "attributes": {
      "emails": ["sally.smith@acme.example.com"],
      "firstName": "Sally",
      "title": "CEO"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": 1
        }
      }
    }
  }
}

Response

{
  "data": {
    "type": "prospect",
    "id": 1,
    "attributes": {
      "createdAt": "2017-01-01T00:00:00",
      "emails": ["sally.smith@acme.example.com"],
      "firstName": "Sally",
      "lastName": "Smath",
      "title": "CEO",
      "updatedAt": "2017-01-01T00:00:00",
      ...
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": 1
        }
      },
      ...
    }
  }
}

To update an existing prospect:

Request

PATCH https://api.outreach.io/api/v2/prospects/1

{
  "data": {
    "type": "prospect",
    "id": 1,
    "attributes": {
      "lastName": "Smith"
    },
    "relationships": {
      "owner": {
        "data": {
          "type": "user",
          "id": 1
        }
      }
    }
  }
}

Response

{
  "data": {
    "type": "prospect",
    "id": 1,
    "attributes": {
      "createdAt": "2017-01-01T00:00:00",
      "emails": ["sally.smith@acme.example.com"],
      "firstName": "Sally",
      "lastName": "Smith",
      "title": "CEO",
      "updatedAt": "2017-01-01T01:00:00",
      ...
    },
    "relationships": {
      "account": {
        "data": {
          "type": "account",
          "id": 1
        }
      },
      "owner": {
        "data": {
          "type": "user",
          "id": 1
        }
      },
      ...
    }
  }
}

The request only included one changed attribute and one new relationship, but the response included all of the prospect’s attributes and relationships. Remember that the Outreach API will only change the fields you provide.

For more information, see the Account and Prospect API Reference pages.

Setup and Manage Sequences

Sequences are at the heart of Outreach’s system of engagement. The Outreach API provides the ability to create and manage sequences and their related rulesets and sequence steps.

To create a new sequence, provide a short name and description, and specify a sequence type of "interval" or "date":

POST https://api.outreach.io/api/v2/sequences

{
  "data": {
    "type": "sequence",
    "attributes": {
      "description": "Primary Sales Sequence",
      "name": "Primary",
      "sequenceType": "interval"
    }
  }
}

We picked "interval" to indicate that this sequence’s steps are separated by an interval of days. Alternatively, we could have picked "date" to indicate that each step should advance at a specific date and time in the future.

Once you have the ID from the response of the create request, you can add the first sequence step. For this step we’ll need to provide its step type and a time interval (in minutes), along with the sequence details:

POST https://api.outreach.io/api/v2/sequenceSteps

{
  "data": {
    "type": "sequenceStep",
    "attributes": {
      "interval": 120,
      "stepType": "call"
    },
    "relationships": {
      "sequence": {
        "data": {
          "type": "sequence",
          "id": 1
        }
      }
    }
  }
}

Accepted values for the step type attribute include "auto_email", "call", "manual_email" and "task". And if this step’s sequence has a sequence type set to "date", then we must instead provide a "date" attribute rather than an "interval" attribute.

You can also associate custom rulesets with sequences. First, create a new ruleset with a name and some settings:

POST https://api.outreach.io/api/v2/rulesets

{
  "data": {
    "type": "ruleset",
    "id": 1,
    "attributes": {
     "autoResumeOotoProspects": true,
     "name": "Custom Ruleset",
     "permitDuplicateProspects": "onlyIfActive"
    }
  }
}

Then associate the ruleset with the existing sequence:

PATCH https://api.outreach.io/api/v2/sequences/1

{
  "data": {
    "type": "sequence",
    "id": 1,
    "relationships": {
      "ruleset": {
        "data": {
          "type": "ruleset",
          "id": 1
        }
      }
    }
  }
}

For more information, see the Sequence, Ruleset and Sequence Step API Reference pages.

Save Snippets and Templates

Snippets and templates are valuable resources that save your team time and energy. Snippets provide easy access to your most commonly used HTML passages. Templates are larger resources that encapsulate a mailing’s subject and body and can be associated with automated mailing sequence steps and one-off tasks. Templates can also contain a default list of recipients relevant to that topic.

To create a snippet, just provide the resource a name and the body’s HTML representation:

Request

POST https://api.outreach.io/api/v2/snippets

{
  "data": {
    "type": "snippet",
    "attributes": {
      "bodyHtml": "<p>Would you please include in your response ...</p>",
      "name": "Request for Information"
    }
  }
}

Response

{
  "data": {
    "type": "snippet",
    "id": 1,
    "attributes": {
      "bodyHtml": "<p>Would you please include in your response ...</p>",
      "name": "Request for Information"
    },
    "relationships": {
      "owner": {
        "data": {
          "type": "user",
          "id": 1
        }
      }
    }
  }
}

Templates are created in a similar fashion, but also contain relationship links to their related mailings, sequence templates and tasks. An example template may look like:

{
  "data": {
    "type": "template",
    "id": 1,
    "attributes": {
      "bodyHtml": "<p>I'd like to introduce you to our new product...",
      "ccRecipients": ["product@company.example.com"],
      "name": "Product Announcement"
    },
    "relationships": {
      "mailings": {
        "links": {
          "related": "https://api.outreach.io/api/v2/mailings?filter[template][id]=1"
        },
      },
      "owner": {
        "data": {
          "type": "user",
          "id": 1
        },
      },
      "sequenceTemplates": {
        "links": {
          "related": "https://api.outreach.io/api/v2/sequenceTemplates?filter[template][id]=1"
        },
      },
      "tasks": {
        "links": {
          "related": "https://api.outreach.io/api/v2/tasks?filter[template][id]=1"
        },
      }
    }
  }
}

Templates can be associated with mailings, sequence templates and tasks when creating or updating those resources. For example, we could associate this template with a brand new sequence template set to "auto_email" mode that will send two days after the previous step:

POST https://api.outreach.io/api/v2/sequenceSteps

{
  "data": {
    "type": "sequenceStep",
    "attributes": {
      "interval": 2880,
      "stepType": "auto_email"
    },
    "relationships": {
      "sequence": {
        "data": {
          "type": "sequence",
          "id": 1
        }
      }
    }
  }
}

// Assuming this returns an id of 1 for our sequenceStep

POST https://api.outreach.io/api/v2/sequenceTemplates

{
  "data": {
    "type": "sequenceTemplate",
    "relationships": {
      "sequenceStep": {
        "data": {
          "type": "sequenceStep",
          "id": 1
        }
      },
      "template": {
        "data": {
          "type": "template",
          "id": 1
        }
      }
    }
  }
}

You can also create unnamed templates that will be unavailable in a list of templates in the UI or from the API index action, but can still be associated with a sequence template in order to help prevent accidental editing of a template used for sequences.

POST https://api.outreach.io/api/v2/templates
{
  "data": {
    "type": "template",
    "attributes": {
      "bodyHtml": "<h1>Greetings!</h1>",
      "subject": "Hello prospect",

    }
  }
}

In order to remove the association of a sequence template to a sequence step, you must destroy the sequence template object.

For more information, see the Snippet and Template API Reference pages.

Add Prospects to Sequences

Prospects can be added and removed from sequences at any time. The Outreach API encapsulates the concept of a prospect within a sequence as a sequence state resource. To start engaging a prospect, create a sequence state resource referencing the relevant prospect, sequence and user’s mailbox:

Request

POST https://api.outreach.io/api/v2/sequenceStates

{
  "data": {
    "type": "sequenceState",
    "relationships": {
      "prospect": {
        "data": {
          "type": "prospect",
          "id": 1
        }
      },
      "sequence": {
        "data": {
          "type": "sequence",
          "id": 1
        }
      },
      "mailbox": {
        "data": {
          "type": "mailbox",
          "id": 1
        }
      }
    }
  }
}

Response

{
  "data": {
    "type": "sequenceState",
    "id": 1,
    "attributes": {
      "createdAt": "2017-01-01T00:00:00",
      "state": "active",
      "stateChangedAt": "2017-01-01T00:00:00",
      "updatedAt": "2017-01-01T00:00:00",
      ...
    }
    "relationships": {
      "prospect": {
        "data": {
          "type": "prospect",
          "id": 1
        }
      },
      "sequence": {
        "data": {
          "type": "sequence",
          "id": 1
        }
      },
      "sequenceStep": {
        "data": {
          "type": "sequenceStep",
          "id": 1
        }
      },
      "mailbox": {
        "data": {
          "type": "mailbox",
          "id": 1
        }
      }
    }
  }
}

Once created, the associated sequence’s automation will begin. You can see that the first sequence step has already been associated with this sequence state. In addition, its state attribute has been set to "active"; additional values include "pending", "finished", "paused", "disabled", "failed", "bounced" and "opted_out". Retrieve sequence states at later times to discover changes to its state and step.

To finish a prospect in a sequence, make a request to the sequence state’s finish action:

POST https://api.outreach.io/api/v2/sequenceStates/1/actions/finish

You can also pause active sequence states as well as resume those that have been paused.

For more information, see the Sequence State API Reference pages.

Schedule Mailings and Tasks

In addition to sequence-based automation, Outreach provides the ability to schedule one-off mailings and tasks.

More information coming soon.

Discover Open Tasks

Outreach can automatically assign users tasks when certain events occur to help streamline their workflow. The Outreach API can help identify new tasks and provide the oppurtunity to take the necessary action. To return just the tasks that a user can currently take action on, you can filter the task list by those with an "incomplete" state belonging to a given user. And to make the action step easier, you can include the task’s related prospect:

GET https://api.outreach.io/api/v2/tasks?filter[state]=incomplete&filter[user][id]=1&include=prospect

Task resources contain an action attribute that describes what type of action the user needs to take, which can be one of "action_item", "call", "email" or "in_person". Along with the task note and its related prospect, you’re ready to take action!

For more information, see the Task API Reference page.

Log External Calls

Logging calls in Outreach is easy. In addition to the calling user and prospect, you’ll just need to specify a call direction and outcome. The direction must be either "inbound" or "outbound" and the outcome must be either "completed" or "no_answer". You’ll likely also want to provide the time when the call was answered and completed.

POST https://api.outreach.io/api/v2/calls

{
  "data": {
    "type": "call",
    "attributes": {
      "answeredAt": "2017-01-01T12:00:15",
      "completedAt": "2017-01-01T12:00:00",
      "direction": "outbound",
      "outcome": "completed"
    },
    "relationships": {
      "prospect": {
        "data": {
          "type": "prospect",
          "id": 1
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": 1
        }
      }
    }
  }
}

If there’s an existing open call task, then you may specify that task relationship when logging the call. The created call will be associated with the task, but the task itself will not be affected.

POST https://api.outreach.io/api/v2/calls

{
  "data": {
    "type": "call",
    "attributes": {
      "direction": "outbound",
      "outcome": "no_answer"
    },
    "relationships": {
      "prospect": {
        "data": {
          "type": "prospect",
          "id": 1
        }
      },
      "task": {
        "data": {
          "type": "task",
          "id": 1
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": 1
        }
      }
    }
  }
}

To additionally indicate that the related task has been completed, pass meta information to the task relationship itself.

POST https://api.outreach.io/api/v2/calls

{
  "data": {
    "type": "call",
    "attributes": {
      "direction": "outbound",
      "note": "Meeting Booked!",
      "outcome": "completed"
    },
    "relationships": {
      "prospect": {
        "data": {
          "type": "prospect",
          "id": 1
        }
      },
      "task": {
        "data": {
          "type": "task",
          "id": 1
        },
        "meta": {
          "complete": true
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": 1
        }
      }
    }
  }
}

For more information, see the Call API Reference page, along with the related Call Disposition and Call Purpose reference pages.

Download Event Activity

Outreach logs numerous events when various activities occur throughout the platform. Collecting these events helps provide insight into a user and their organization’s activity.

To download the most recent events, sort in a descending order based on the updatedAt timestamp:

Request

GET https://api.outreach.io/api/v2/events?sort=-updatedAt

Response

{
  "data": [{
    "type": "event",
    "id": 1,
    "attributes": {
      "createdAt": "2017-01-01T00:00:00",
      "name": "prospect_updated",
      "updatedAt": "2017-01-01T00:00:00",
      ...
    }
  },
  ...
  ]
}

More information on event payloads and relationships coming soon.

Collect Platform Statistics

Until the Outreach API supports better analytics resources, you can still collect statistics directly from the core resources. A number of mailing-related resources provide delivery information, including mailings, prospects, sequences, sequence states, sequence steps and templates.

For example, to retrieve mailing delivery statistics for prospects, specify sparse fieldsets to get just the attributes that you are looking for:

Request

GET https://api.outreach.io/api/v2/prospects?fields[prospect]=clickCount,openCount,replyCount

Response

{
  "data": [{
    "type": "prospect",
    "id": 1,
    "attributes": {
      "clickCount": 2,
      "openCount": 9,
      "replyCount": 1
    }
  },
  ...
  ]
}

Note that these counts reference the total number of events across all of the prospect’s mailings since the last touch point. These counts are not the unique number of associated mailings that have received those events.

Continue reading the API Reference for detailed descriptions of all available attributes.

Respond to Platform Events

The Outreach API normally requires your action to retrieve, create or update resources. But with Webhooks, the Outreach API will automatically notify you whenever events that you are interested in occur. You can create webhooks just like any other resource. You must provide an HTTPS URL, and you can optionally specify the resources and actions that this webhook will respond to. By default, those values will be an asterisk *, which indicates that all applicable resources and actions will be delivered. Possible values include:

When an active webhook sees a change to an applicable resource-action combination, the Outreach API will POST a JSON-API-styled request to the webhook’s URL. Please note that create and update actions will contain only created/changed attributes, while deleted actions will contain the last known set of attributes and relationships before the resource was deleted.

For example, to create a webhook that will trigger after each “task completed” event:

Request

POST https://api.outreach.io/api/v2/webhooks

{
  "data": {
    "type": "webhook",
    "attributes": {
      "action": "completed",
      "resource": "task",
      "url": "https://foo.bar/webhooks"
    }
  }
}

Response

{
  "data": {
    "type": "webhook",
    "id": 1,
    "attributes": {
      "action": "completed",
      "active": true,
      "resource": "task",
      "secret": null,
      "url": "https://foo.bar/webhooks"
    }
  }
}

When a task-completed event occurs, a JSON-API-styled request will be sent to the webhook’s URL that includes the changed attributes and meta information about the webhook event.

Webhook Request

POST https://foo.bar/webhooks

{
  "data": {
    "type": "task",
    "id": 1,
    "attributes": {
      "completed": true,
      "completedAt": "2017-01-01T00:00:00",
      "state": "completed"
    },
    "meta": {
      "deliveredAt": "2017-01-01T00:00:01",
      "eventName": "task.completed"
    }
  }
}

For added protection, you can provide the webhook with a secret attribute. If that value is present, we’ll include an Outreach-Webhook-Signature header that is the HMAC hexdigest of the secret and the payload body, which you can use to verify the integrity of the request.

For example, to verify the integrity of an incoming webhook in Ruby:

SECRET = "foo" # Same as is saved in the Outreach webhook

def verified?(headers, body)
  headers["Outreach-Webhook-Signature"] == signature(body)
end

def signature(body)
  OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), SECRET, body)
end

Invite New Users

You can invite new users to the Outreach platform and manage their identies using the Outreach API. Create new users just like any other resource:

Webhook Request

POST https://api.outreach.io/api/v2/users

{
  "data": {
    "type": "user",
    "attributes": {
      "email": "foo@bar.com",
      "firstName": "Foo",
      "lastName": "Bar"
    }
  }
}

Response

{
  "data": {
    "type": "user",
    "id": 1,
    "attributes": {
      "email": "foo@bar.com",
      "firstName": "Foo",
      "lastName": "Bar"
    }
  }
}

By default all new users will receive an email invitation with instructions on how to get started. You can prevent email invitations from being sent by including an additional meta data parameter:

Request

POST https://api.outreach.io/api/v2/users

{
  "data": {
    "type": "user",
    "attributes": {
      "email": "foo@bar.com",
      "firstName": "Foo",
      "lastName": "Bar"
    },
    "meta": {
      "sendInvite": false
    }
  }
}

Create Compliance Requests

Outreach provides a compliance request API for processing delete requests in compliance with regulations such as CCPA and GDPR. This request will be processed asynchronously, deletion may not be processed immediately.

To submit a request to permanently delete a prospect or individual in Outreach, include the following attributes to a POST request:

Request

POST https://api.outreach.io/api/v2/complianceRequests

{
  "data": {
    "type": "complianceRequest",
    "attributes": {
      "requester_email": "admin@example.com",
      "request_type": "Delete",
      "object_type": "Prospect",
      "request_object_email": "prospect_email@example.com"
    }
  }
}

Response

{
  "data": {
    "batch_compliance_request_id": "f98711fe-8a03-48b9-91d3-0f7994e999cc"
  }
}

Submitting a compliance request will trigger a batch of tasks to be processed. To view the status of the submitted request, use the batch compliance request filter on the following GET request.

Request

GET https://api.outreach.io/api/v2/complianceRequests?filter[batchComplianceRequest]=f98711fe-8a03-48b9-91d3-0f7994e999cc

A compliance request may have any of the following states to indicate its current processing status:

A compliance request consists of multiple tasks targeting different elements of the request. Each task may also have its own state, shown below:

The only permanent state for a task or request is the done state, any failures will be retried until successful.

For more information on compliance requests, contact Outreach support at support@outreach.io.

Deprecated features

May, 2023

Outreach is continuously looking for ways to improve performance and give developers greater flexibility in using our APIs. In a recently conducted review, we identified three API behaviors that have the potential to introduce performance and data inconsistency issues. Since the issues resulting from these API behaviors outweigh their benefits, we have decided to deprecate these API behaviors on October 31, 2023.

The deprecation is effective immediately for any new integrations and integrations that have not used these features in the last four months. Integrations that used at least one of the deprecated features will be able to operate till October 31, 2023.

In order to maintain the performance and reliability of our API services and allow modernization of our service architecture, Outreach has decided to deprecate the following API features:

Sorting by relationship’s attribute

Please fetch the result of your query with the relationship’s attribute included and apply sorting locally in your service.

Before:

# instead of sorting tasks by prospect’s name
curl -s -H "$AUTH" "$HOSTNAME/api/v2/tasks?filter[dueAt]=2023-04-10..inf&sort=prospect.firstName"

After:

# fetch tasks with prospect’s name included
curl -s -H "$AUTH" "$HOSTNAME/api/v2/tasks?filter[dueAt]=2023-04-10..inf&include=prospect&fields[prospect]=name" > tasks.json

# prepare map for sorting
jq '[.included[] | {"\(.id)":.attributes.name}] | add' tasks.json > sort_by.json

# sort tasks by prepared map
jq --slurpfile m sort_by.json '.data | sort_by($m[0]["\(.relationships.prospect.data.id)"])' tasks.json

Including related objects to the response of create or update operation

Plese replace the single POST/PATCH request with two: POST/PATCH of the main object followed by GET request for related objects.

Before:

curl -s -H "$AUTH" -X POST "$HOSTNAME/api/v2/prospects?include=account" -H 'Content-Type: application/vnd.api+json' \
     -d '{"data":{"type":"prospect","attributes":{"company":"Acme Corp.","emails":["jane@acme.com"],"firstName":"Jane","lastName":"Doe"}}}'

After:

# create or update the object without including related objects
curl -s -H "$AUTH" -X POST "$HOSTNAME/api/v2/prospects" -H 'Content-Type: application/vnd.api+json' \
     -d '{"data":{"type":"prospect","attributes":{"company":"Acme Corp.","emails":["jane@acme.com"],"firstName":"Jane","lastName":"Doe"}}}' \
     > prospect.json

# get the IDs you need from the response
PROSPECT_ID=`jq .data.id prospect.json`
ACCOUNT_ID=`jq .data.relationships.account.data.id prospect.json`

# and fetch the related object directly
curl -s -H "$AUTH" "$HOSTNAME/api/v2/accounts/$ACCOUNT_ID"
# alternatively you can refetch the main object with included related objects
curl -s -H "$AUTH" -X GET "$HOSTNAME/api/v2/prospects/$PROSPECT_ID?include=account"

Filters by relationship’s attribute for some of the endpoints or relations

Please consult the reference documentation for each relationship to see whether you can use filters by relationship’s attributes, relationship id only, or not even that.

If filtering is alowed by id only, split the original single request to two, get ids of related object(s) in the first request and pass them to the adjusted original request.

Before:

# instead of sequence.name filter in 2 steps by sequence.id as that is supported
curl -s -H "$AUTH" "$HOSTNAME/api/v2/mailings?filter[sequence][name]=ABCD"

After:

# fetch IDs of sequences first (no need to fetch any attributes)
curl -s -H "$AUTH" "$HOSTNAME/api/v2/sequences?filter[name]=ABCD&fields[sequence]=" > sequences.json
SEQ_IDS=`jq -r '[.data[] | .id] | join(",")' sequences.json`

# then fetch the objects by IDs of related objects
curl -s -H "$AUTH" "$HOSTNAME/api/v2/mailings?filter[sequence][id]=$SEQ_IDS"

If filtering by the relationship is not allowed, query the related object and include the original one. This workaround applies if you want to obtain parent entity (e.g. account) filtered by child entity (e.g. prospect). Also in the specific case of accounts/prospects you might want to exclude unnamed accounts from the response as those are not returned by /api/v2/accounts endpoint by default.

Before:

# instead of filtering accounts by prospect filter prospects and include accounts as that is supported
curl -s -H "$AUTH" "$HOSTNAME/api/v2/accounts?filter[prospects][updatedAt]=2023-04-14..inf"

After:

# fetch IDs of prospects only (no need to fetch any attributes as we want accounts)
# in this case we should exclude unnamed accounts which are not returned by original query
curl -s -H "$AUTH" "$HOSTNAME/api/v2/prospects?filter[updatedAt]=2023-04-14..inf&fields[prospect]=&include=account" \
  | jq '.included[] | select(.attributes.named)'

API Reference

Audit

Events that happen during the day. Things like login, plugin mapping changes, etc.

Links

instances

GET https://api.outreach.io/api/v2/audits

Account

A descriptor of a named company used to categorize prospects within an account-based sales approach.

Links

instances

GET https://api.outreach.io/api/v2/accounts

create

POST https://api.outreach.io/api/v2/accounts

self

GET https://api.outreach.io/api/v2/accounts/{:id}

update

PATCH https://api.outreach.io/api/v2/accounts/{:id}

destroy

DELETE https://api.outreach.io/api/v2/accounts/{:id}

Resource Metadata

Call Disposition

A ready-made collection of call dispositions that help categorize your call logs.

Links

instances

GET https://api.outreach.io/api/v2/callDispositions

create

POST https://api.outreach.io/api/v2/callDispositions

self

GET https://api.outreach.io/api/v2/callDispositions/{:id}

update

PATCH https://api.outreach.io/api/v2/callDispositions/{:id}

destroy

DELETE https://api.outreach.io/api/v2/callDispositions/{:id}

Resource Metadata

Call Purpose

A ready-made collection of call purposes that help categorize your call logs.

Links

instances

GET https://api.outreach.io/api/v2/callPurposes

create

POST https://api.outreach.io/api/v2/callPurposes

self

GET https://api.outreach.io/api/v2/callPurposes/{:id}

update

PATCH https://api.outreach.io/api/v2/callPurposes/{:id}

destroy

DELETE https://api.outreach.io/api/v2/callPurposes/{:id}

Resource Metadata

Call

A log of an inbound or outbound call made with a prospect.

Links

instances

GET https://api.outreach.io/api/v2/calls

create

POST https://api.outreach.io/api/v2/calls

self

GET https://api.outreach.io/api/v2/calls/{:id}

destroy

DELETE https://api.outreach.io/api/v2/calls/{:id}

Resource Metadata

Compliance Request

A regulatory request to delete or export an individual's PII.

Links

instances

GET https://api.outreach.io/api/v2/complianceRequests

create

POST https://api.outreach.io/api/v2/complianceRequests

self

GET https://api.outreach.io/api/v2/complianceRequests/{:id}

CustomDuty

A freeform user-specified role or job duty played by a user in their organization.

Links

create

POST https://api.outreach.io/api/v2/customDuties

Content Category

Content can be grouped into content categories to help discoverability.

Links

instances

GET https://api.outreach.io/api/v2/contentCategories

create

POST https://api.outreach.io/api/v2/contentCategories

self

GET https://api.outreach.io/api/v2/contentCategories/{:id}

update

PATCH https://api.outreach.io/api/v2/contentCategories/{:id}

destroy

DELETE https://api.outreach.io/api/v2/contentCategories/{:id}

Resource Metadata

Content Category Membership

A record that maps content (e.g. a sequence) to a content category.

Links

instances

GET https://api.outreach.io/api/v2/contentCategoryMemberships

create

POST https://api.outreach.io/api/v2/contentCategoryMemberships

self

GET https://api.outreach.io/api/v2/contentCategoryMemberships/{:id}

destroy

DELETE https://api.outreach.io/api/v2/contentCategoryMemberships/{:id}

Resource Metadata

Content Category Ownership

A record that maps content categories to owners. This allows categories to be linked to one or more teams.

Links

instances

GET https://api.outreach.io/api/v2/contentCategoryOwnerships

create

POST https://api.outreach.io/api/v2/contentCategoryOwnerships

destroy

DELETE https://api.outreach.io/api/v2/contentCategoryOwnerships/{:id}

Resource Metadata

Duty

An Outreach-suggested role or job duty played by a user in their organization.

Links

instances

GET https://api.outreach.io/api/v2/duties

Email Address

A prospect's email address

Links

instances

GET https://api.outreach.io/api/v2/emailAddresses

create

POST https://api.outreach.io/api/v2/emailAddresses

self

GET https://api.outreach.io/api/v2/emailAddresses/{:id}

update

PATCH https://api.outreach.io/api/v2/emailAddresses/{:id}

destroy

DELETE https://api.outreach.io/api/v2/emailAddresses/{:id}

Resource Metadata

Event

Application events, capturing details around the initiator, recipient, etc.

Links

instances

GET https://api.outreach.io/api/v2/events

create

POST https://api.outreach.io/api/v2/events

self

GET https://api.outreach.io/api/v2/events/{:id}

Resource Metadata

Favorite

A record (Prospect, Account, Sequence, etc.) favorited by a particular user.

Links

instances

GET https://api.outreach.io/api/v2/favorites

create

POST https://api.outreach.io/api/v2/favorites

self

GET https://api.outreach.io/api/v2/favorites/{:id}

destroy

DELETE https://api.outreach.io/api/v2/favorites/{:id}

Resource Metadata

Mail Alias

Alternative email name for a mailbox.

Links

instances

GET https://api.outreach.io/api/v2/mailAliases

self

GET https://api.outreach.io/api/v2/mailAliases/{:id}

Mailbox

A representation of an email mailbox, used within the application for sending and syncing emails.

Member Actions

test_send

Test if sending emails works from this mailbox.

test_sync

Test if syncing emails works from this mailbox.

error_sync

Signaling that the mailbox sync errored.

link_ews_master_account

Link mailbox with EWS master account

unlink_ews_master_account

Unlink EWS master account from mailbox

Links

instances

GET https://api.outreach.io/api/v2/mailboxes

create

POST https://api.outreach.io/api/v2/mailboxes

self

GET https://api.outreach.io/api/v2/mailboxes/{:id}

update

PATCH https://api.outreach.io/api/v2/mailboxes/{:id}

destroy

DELETE https://api.outreach.io/api/v2/mailboxes/{:id}

test_send

POST https://api.outreach.io/api/v2/mailboxes/{:id}/actions/testSend

test_sync

POST https://api.outreach.io/api/v2/mailboxes/{:id}/actions/testSync

error_sync

POST https://api.outreach.io/api/v2/mailboxes/{:id}/actions/errorSync

link_ews_master_account

POST https://api.outreach.io/api/v2/mailboxes/{:id}/actions/linkEwsMasterAccount

unlink_ews_master_account

POST https://api.outreach.io/api/v2/mailboxes/{:id}/actions/unlinkEwsMasterAccount

Resource Metadata

Mailing

A representation of a platform-related email.

Links

instances

GET https://api.outreach.io/api/v2/mailings

create

POST https://api.outreach.io/api/v2/mailings

self

GET https://api.outreach.io/api/v2/mailings/{:id}

Resource Metadata

Opportunity

An opportunity for a sale or pending deal. Requires the Opportunities SKU to be enabled in order to have access. Please contact support for more assistance.

Links

instances

GET https://api.outreach.io/api/v2/opportunities

create

POST https://api.outreach.io/api/v2/opportunities

self

GET https://api.outreach.io/api/v2/opportunities/{:id}

update

PATCH https://api.outreach.io/api/v2/opportunities/{:id}

destroy

DELETE https://api.outreach.io/api/v2/opportunities/{:id}

Resource Metadata

Opportunity Prospect Role

A prospect's role and association with an opportunity

Links

instances

GET https://api.outreach.io/api/v2/opportunityProspectRoles

create

POST https://api.outreach.io/api/v2/opportunityProspectRoles

self

GET https://api.outreach.io/api/v2/opportunityProspectRoles/{:id}

update

PATCH https://api.outreach.io/api/v2/opportunityProspectRoles/{:id}

destroy

DELETE https://api.outreach.io/api/v2/opportunityProspectRoles/{:id}

Resource Metadata

Opportunity Stage

The stage an opportunity is in. Requires the Opportunities SKU to be enabled in order to have access. Please contact support for more assistance.

Links

instances

GET https://api.outreach.io/api/v2/opportunityStages

create

POST https://api.outreach.io/api/v2/opportunityStages

self

GET https://api.outreach.io/api/v2/opportunityStages/{:id}

update

PATCH https://api.outreach.io/api/v2/opportunityStages/{:id}

destroy

DELETE https://api.outreach.io/api/v2/opportunityStages/{:id}

Resource Metadata

Persona

A descriptor of a person, used for categorizing Prospects.

Links

instances

GET https://api.outreach.io/api/v2/personas

create

POST https://api.outreach.io/api/v2/personas

self

GET https://api.outreach.io/api/v2/personas/{:id}

update

PATCH https://api.outreach.io/api/v2/personas/{:id}

destroy

DELETE https://api.outreach.io/api/v2/personas/{:id}

Resource Metadata

Phone Number

A prospect's phone number

Links

instances

GET https://api.outreach.io/api/v2/phoneNumbers

create

POST https://api.outreach.io/api/v2/phoneNumbers

self

GET https://api.outreach.io/api/v2/phoneNumbers/{:id}

update

PATCH https://api.outreach.io/api/v2/phoneNumbers/{:id}

destroy

DELETE https://api.outreach.io/api/v2/phoneNumbers/{:id}

Resource Metadata

Profile

Controls what you can see and do within Outreach

Member Actions

ensure_special_profile_exists

Creates or Finds profile with provided special_id.

Links

instances

GET https://api.outreach.io/api/v2/profiles

create

POST https://api.outreach.io/api/v2/profiles

self

GET https://api.outreach.io/api/v2/profiles/{:id}

update

PATCH https://api.outreach.io/api/v2/profiles/{:id}

destroy

DELETE https://api.outreach.io/api/v2/profiles/{:id}

ensure_special_profile_exists

POST https://api.outreach.io/api/v2/profiles/{:id}/actions/ensureSpecialProfileExists

Resource Metadata

Prospect

A descriptor of a person.