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, follow the steps described at Setting up OAuth. 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:
Copy
Copied
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

Copy
Copied
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

Copy
Copied
{
  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

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

Response

Copy
Copied
{
  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:

Copy
Copied
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:
Copy
Copied
{
  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:
Copy
Copied
{
  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.
Copy
Copied
{
  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.
Copy
Copied
{
  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.",
    },
  ],
}