API access

Outreach currently enables access to the REST API via API calls authenticated via OAuth 2.0 protocol. Additionally a limited set of API endpoints is available through a proprietary s2s protocol.

OAuth in a nutshell

OAuth 2.0 is a standard authorization protocol and there is a lot of information online on how to implement it. Here is how it works in a nutshell:

  1. User clicks on an authorization URL like this one.
  2. At the authorization page user is informed about which data your application intends to use and gives his consent to do so.
  3. Following the consent Outreach redirects the user to the URL on your server passing along a code query parameter also known as the Authorization Grant.
  4. You use the Authorization Grant to obtain the Access Token.
  5. With the Access Token you call the Outreach REST API endpoints. Outreach will execute all the calls on behalf of the user who performed authorization.

Setting up OAuth

To begin using the REST API you need to create an Outreach app. Then go to the API access tab to configure access specifics. You'll need to specify one or more redirect URI's and select the OAuth data scopes that your application intends to use. Please select at least one scope and specify at least one redirect URI.


OAuth credentials

For each Outreach app, the development and production credentials are generated.

  • Development credentials are provisioned immediately and are intended to be used during application development. Any change (e.g. scopes) is applied immediately on save.
  • Production credentials are provisioned after the app goes through the publishing process

If an end-user goes through OAuth flow that contains development credentials they will be warned that the application is not production ready.


Please be aware that OAuth client secrets will be displayed only once, when generated. You cannot display them again. Use the "Regenerate" button to create new secrets if necessary.

Requesting access token

Following user authorization browser will redirect the user to the specified redirect URI containing the authorization grant: <redirect_uri>?code=<authorization_grant>. Read the value of the code parameter and pass it to https://api.outreach.io/oauth/token to get your OAuth token for this user:
curl https://api.outreach.io/oauth/token \
  -X POST \
  -d client_id=<client_id> \
  -d client_secret=<client_secret> \
  -d redirect_uri=<redirect_uri> \
  -d grant_type=authorization_code \
  -d code=<authorization_grant>

This call will only be successful if all of the parameter values match exactly the values which initiated this OAuth flow.

In some situations you may need to set up different redirect URIs for development and production client IDs so that you know which credential (prod or dev) you need to use in the above call. Alternatively you can use the state query parameter when initiating the OAuth flow. For example the flow initiated with:
will redirect the client to your server while maintaining the value of the dev parameter <redirect_uri>?code=<authorization_grant>&state=dev. You can then read the value of the state parameter and choose the correct credential for the token acquisition call.