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

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.) If the access token expires, you can retrieve a new one by using the "refresh_token" grant type and by passing the refresh token to the code parameter:

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.

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 5,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 5,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, Sort and Paginate Collections

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

Filter parameters restrict collections by certain key-value combinations; the sort parameter orders collections by attributes and relationships’ attributes; and the page limit and offset parameters limit views into large collections. 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

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

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 options 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[score]=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

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

Sort by multiple criteria

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

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.

Limit the page size

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

Note that page limits must not be larger than 100.

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.

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

Note: You can specify sparse fieldsets and included resources for create actions just like you can when fetching resources.

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.

Note: You can specify sparse fieldsets and included resources for update actions just like you can when fetching resources.

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?action[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 remove a prospect from a sequence, delete its related sequence state:

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

Note that soon you will be able to perform additional actions, including update, advance and finish the sequence state directly.

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]=bounceCount,clickCount,deliverCount,openCount,optOutCount,replyCount

Response

{
  "data": [{
    "type": "prospect",
    "id": 1,
    "attributes": {
      "bounceCount": 0,
      "clickCount": 2,
      "deliverCount": 5,
      "openCount": 9,
      "optOutCount": 0,
      "replyCount": 1
    }
  },
  ...
  ]
}

Note that these counts reference the total number of events across all of the prospect’s mailings, not just 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:

Resource Actions
* * created updated destroyed
account * created updated destroyed
call * created updated destroyed
mailing * created updated destroyed bounced delivered opened replied
prospect * created updated destroyed
sequence * created updated destroyed
sequenceState * created updated destroyed advanced finished
task * created updated destroyed completed

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
    }
  }
}

API Reference

Account

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

Attribute Name Description Notes
companyType
string
A description of the company’s type (e.g. "Public Company").
createdAt
date-time
The date and time the account was created. readonly filterable sortable
custom1
string
The value of the account’s first custom field.
custom10
string
The value of the account’s 10th custom field.
custom11
string
The value of the account’s 11th custom field.
custom12
string
The value of the account’s 12th custom field.
custom13
string
The value of the account’s 13th custom field.
custom14
string
The value of the account’s 14th custom field.
custom15
string
The value of the account’s 15th custom field.
custom16
string
The value of the account’s 16th custom field.
custom17
string
The value of the account’s 17th custom field.
custom18
string
The value of the account’s 18th custom field.
custom19
string
The value of the account’s 19th custom field.
custom2
string
The value of the account’s second custom field.
custom20
string
The value of the account’s 20th custom field.
custom21
string
The value of the account’s 21th custom field.
custom22
string
The value of the account’s 22th custom field.
custom23
string
The value of the account’s 23th custom field.
custom24
string
The value of the account’s 24th custom field.
custom25
string
The value of the account’s 25th custom field.
custom26
string
The value of the account’s 26th custom field.
custom27
string
The value of the account’s 27th custom field.
custom28
string
The value of the account’s 28th custom field.
custom29
string
The value of the account’s 29th custom field.
custom3
string
The value of the account’s third custom field.
custom30
string
The value of the account’s 30th custom field.
custom31
string
The value of the account’s 31th custom field.
custom32
string
The value of the account’s 32th custom field.
custom33
string
The value of the account’s 33th custom field.
custom34
string
The value of the account’s 34th custom field.
custom35
string
The value of the account’s 35th custom field.
custom4
string
The value of the account’s fourth custom field.
custom5
string
The value of the account’s fifth custom field.
custom6
string
The value of the account’s sixth custom field.
custom7
string
The value of the account’s seventh custom field.
custom8
string
The value of the account’s eight custom field.
custom9
string
The value of the account’s ninth custom field.
customId
string
A custom ID for the account, often referencing an ID in an external system. filterable sortable
description
string
A custom description of the account.
domain
string
The company’s website domain (e.g. "www.acme.com"). filterable sortable
externalSource
string
The source of the resource’s creation (e.g. "outreach-api"). readonly
followers
number
The number of followers the company has listed on social media.
foundedAt
date-time
The founding date of the company.
industry
string
A description of the company’s industry (e.g. "Manufacturing").
linkedInEmployees
number
The number of employees listed on the company’s LinkedIn URL.
linkedInUrl
string
The company’s LinkedIn URL.
locality
string
The company’s primary geographic region (e.g. "Eastern USA").
name
string
The name of the company (e.g. "Acme Corporation"). filterable sortable
named
boolean
A boolean value determining whether this is a "named" account or not. Only named accounts will show up on the collection index. filterable sortable
naturalName
string
The natural name of the company (e.g. "Acme").
numberOfEmployees
number
The number of employees working at the company.
tags
string
A list of tag values associated with the account (e.g. ["Enterprise", "Tier 1"]). filterable
updatedAt
date-time
The date and time the account was last updated. readonly filterable sortable
websiteUrl
string
The company’s website URL (e.g. "https://www.acme.com/contact").
Relationship Name Description Notes
creator The creator of the account. data links readonly
owner The owner of the account. data links
prospects The account's associated prospects. links
tasks The associated tasks. links
updater The most recent updater of the account. data links readonly

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

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta
dataConnections The set of connections a given account has to external sources. provideDataConnections

Call Disposition

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

Attribute Name Description Notes
createdAt
date-time
The date and time the call disposition was created. readonly filterable sortable
name
string
The disposition’s name (e.g. "Meeting Scheduled"). filterable sortable
order
number
The disposition’s display order within the collection. filterable sortable
outcome
string
The disposition’s call outcome; must be either "Answered" or "Not Answered". filterable sortable
updatedAt
date-time
The date and time the call disposition was last updated. readonly filterable sortable
Relationship Name Description Notes
calls The calls made with this disposition. links
creator The creator of the call disposition. data links readonly

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

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta

Call Purpose

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

Attribute Name Description Notes
createdAt
date-time
The date and time the call purpose was created. readonly filterable sortable
name
string
The purpose’s name (e.g. "Initial Contact"). filterable sortable
order
number
The purpose’s display order within the collection. filterable sortable
updatedAt
date-time
The date and time the call purpose was last updated. readonly filterable sortable
Relationship Name Description Notes
calls The calls made with this purpose. links
creator The creator of the call purpose. data links readonly

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

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta

Call

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

Attribute Name Description Notes
answeredAt
date-time
The date and time the call was answered.
completedAt
date-time
The date and time the call was completed.
createdAt
date-time
The date and time the call was created. readonly filterable sortable
direction
string
The call direction from the user’s point of view; must be either "inbound" or "outbound".
from
string
The phone number used to place the call. filterable sortable
note
string
A custom note associated with this call.
outcome
string
The call’s outcome; must be either "Answered" or "Not Answered". filterable sortable
recordingUrl
string
The URL of the call’s audio recording. filterable sortable
returnedAt
date-time
The date and time the call was returned.
sequenceAction
string
The action to take on the associated sequence; must be either "Advance", "Finish", "Finish - No Reply", or "Finish - Replied".
state
string
The call’s current state. readonly filterable sortable
stateChangedAt
date-time
The date and time the call’s state last changed. readonly
tags
string
A list of tag values associated with the call (e.g. ["Interested", "Meeting Booked"]). filterable
to
string
The phone number that the call was placed to. filterable sortable
updatedAt
date-time
The date and time the call was last updated. readonly filterable sortable
userCallType
string
The type of call placed within the Outreach client; must be either "bridge" or "voip". readonly filterable sortable
voicemailRecordingUrl
string
The URL of the call’s voicemail audio recording. readonly
Relationship Name Description Notes
callDisposition The associated call disposition. data links
callPurpose The associated call purpose. data links
prospect The associated prospect. data links
sequence The associated sequence. data links readonly
sequenceState The associated sequence state. data links readonly
sequenceStep The associated sequence step. data links readonly
task The associated task. data links
user The associated user. data links

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

Metadata Name Description Query Param
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta
dataConnections The set of connections a given call has to external sources. provideDataConnections

CustomDuty

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

Attribute Name Description Notes
dutyType
string
The polymorphic type of the duty (not the Ruby type, the duty type).
name
string
The name of the role.

Links

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

Duty

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

Attribute Name Description Notes
dutyType
string
The polymorphic type of the duty (not the Ruby type, the duty type).
symbolicName
string
The string constant used to refer to this duty which can be internationalized on the client.

Links

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

Event

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

Attribute Name Description Notes
createdAt
date-time
The date and time the event was created. readonly filterable sortable
eventAt
date-time
The date and time the event occured. readonly filterable sortable
name
string
The name of the event that took place (e.g. "mailbox_created"). readonly filterable sortable
payload
object
The transmitted data for the event. readonly
requestCity
string
The city where the request that created the event was made. readonly
requestDevice
string
The type of device on which the request that created the event was made. readonly
requestHost
string
Name of the host from which the request was made. readonly
requestProxied
boolean
A boolean value whether the request was proxied. For example, when true the request city refers to the location of the email server and not the prospect. readonly
requestRegion
string
Name of the region from which the request was made. readonly

Links

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

Resource Metadata

Metadata Name Description Query Param
dataConnections The set of connections the event has to external sources. provideDataConnections

Mailbox

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

Attribute Name Description Notes
createdAt
date-time
The date and time the mailbox was created. readonly filterable sortable
email
string
The email address of the mailbox. filterable sortable
emailProvider
string
The mail service provider. While not a required field, it is strongly recommended to use one of 'exchange_online', 'exchange_server', 'gmail', 'gmail_api', 'google_oauth2', 'intermedia', 'office365_oauth2', 'office_365', 'rackspace'. If no value is provided, send and sync will make assumptions based on the ews, imap, and smtp values provided.
emailSignature
string
The default signature, in HTML, to be appended to sent email messages.
ewsEndpoint
string
The url of the Exchange Web Service.
ewsSslVerifyMode
number
The SSL verify mode, represented as an integer, the EWS connection will used. (verify none=0, verify peer=1, verify client once=4, verify fail if no peer cert=2)
exchangeVersion
string
The version of Exchange. Must be one of 'Exchange2007', 'Exchange2007_SP1', 'Exchange2010', 'Exchange2010_SP1', 'Exchange2010_SP2', 'Exchange2013', 'Exchange2013_SP1'.
imapHost
string
The address of the IMAP host, used for syncing (e.g. 'imap.gmail.com').
imapPort
number
The port number the IMAP server is using (e.g. '993').
imapSsl
boolean
A boolean value whether the IMAP connection will use SSL.
maxEmailsPerDay
number
The maximum number of in/out emails per day.
maxMailingsPerDay
number
The maximum number of emails the application can send in a day from this mailbox. Recommended value is 500.
maxMailingsPerWeek
number
The maximum number of emails the application can send within a week from this mailbox. Recommended value is 5000.
optOutMessage
string
The message displayed on the unsubscribe confirmation page, seen after clicking the unsubscribe link in the email (e.g. "To unsubscribe, click the button below.").
optOutSignature
string
The message below the signature, in HTML, when the sequence requires an unsubscribe link (e.g. "If you'd like me to stop sending you emails, please <a href='%unsubscribe_url%'>click here</a>").
password
string
The password of the mailbox. This attribute can be used to set the password, but is not available for read. writeonly
prospectEmailExclusions
string
A list (provided as a string, newline-delimited) of email address patterns to be excluded from syncing (e.g. "*@outreach.io\ndaniel@example.com").
sendDisabled
boolean
A boolean value whether sending is disabled from this mailbox.
sendErroredAt
date-time
The date and time the most recent send error occurred. readonly
sendMaxRetries
number
The maximum number of times to auto-retry a delivery when it fails.
sendMethod
string
The method used for sending email. Must be either 'ews', 'sendgrid', or 'smtp'.
sendPeriod
number
The amount of time in seconds that the number of sendThreshold emails can be sent. Recommended value is two deliveries per minute (sendPeriod is 60).
sendRequiresSync
boolean
A boolean value whether the mailbox is required to be recently synced before sending.
sendSuccessAt
date-time
The date and time the most recent successful email send occurred. readonly
sendThreshold
number
The maximum number of email sends per the sendPeriod amount of time. Recommended value is two deliveries per minute (sendThreshold is 2).
sendgridApiKey
string
The api key of the SendGrid account used for sending. writeonly
sendgridWebhookUrl
string
The endpoint required within the SendGrid account settings to support bounce and spam-report tracking. readonly
smtpHost
string
The address of the SMTP host, used for sending (e.g. 'smtp.gmail.com').
smtpPassword
string
The password for the SMTP account. This value should be left blank unless a separate SMTP account is being used for sending (i.e. not the mailbox's main username/password). writeonly
smtpPort
number
The port number the SMTP server is using (e.g. '587').
smtpSsl
boolean
A boolean value whether the SMTP connection will use SSL.
smtpUsername
string
The username for the SMTP account. This value should be left blank unless a separate SMTP account is being used for sending (i.e. not the mailbox's main username/password).
syncActiveFrequency
number
The amount of time in seconds between syncing when the user is actively using the application.
syncDisabled
boolean
A boolean value whether syncing is disabled from this mailbox.
syncErroredAt
date-time
The date and time the most recent sync error occurred. readonly
syncFinishedAt
date-time
The date and time the most recent sync finished. readonly
syncMethod
string
The method used for syncing email. Must be either 'ews', 'gmail_api', or 'imap'.
syncOutreachFolder
boolean
A boolean value whether the folder for syncing is named 'Outreach' instead of 'Inbox'. Only available for Exchange version 'Exchange2007_SP1'.
syncPassiveFrequency
number
The amount of time in seconds between syncing when the user is not actively using the application.
syncSuccessAt
date-time
The date and time the most recent successful email sync occurred. readonly
updatedAt
date-time
The date and time the mailbox was last updated. readonly filterable sortable
username
string
The username of the email account. While not a required field, a username is necessary for most email providers outside of OAuth. This value is normally the same as the email address.
Relationship Name Description Notes
creator The creator of the mailbox. data links readonly
mailings The mailings sent via this mailbox. links
updater The most recent updater of the mailbox. data links readonly
user The user owning this mailbox. data links

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}

Resource Metadata

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta

Mailing

A representation of a platform-related email.

Attribute Name Description Notes
bodyHtml
string
The mailing's custom email body, represented in HTML. If provided this field will override any associated template.
bodyText
string
The plain-text representation of the 'bodyHTML' field. readonly
bouncedAt
date-time
The date and time the email was bounced. readonly filterable sortable
clickCount
number
The total number of times links within the email were clicked (if the message is tracking links). readonly
clickedAt
date-time
The most recent date and time a link was clicked (if the message is tracking links). readonly filterable sortable
createdAt
date-time
The date and time the mailing was created. readonly filterable sortable
deliveredAt
date-time
The date and time the email was delivered. readonly filterable sortable
errorBacktrace
string
Technical details explaining the mailing's error. readonly
errorReason
string
A summary explaining the mailing's error. readonly
mailboxAddress
string
The email address the mailing was sent from. readonly
mailingType
string
A description of the type of the emailing (e.g. "sequence", "single", "campaign"). readonly filterable sortable
markedAsSpamAt
date-time
The date and time the email was marked as spam. readonly
openCount
number
The total number of times the email was opened (if the message is tracking opens). readonly
openedAt
date-time
The most recent date and time the email was opened (if the message is tracking opens). readonly filterable sortable
overrideSafetySettings
boolean
A boolean value whether users can override submission if template variables have not all been replaced. readonly
references
string
A list of references for the mailing taken from the email header. readonly
repliedAt
date-time
The date and time the email was replied to. readonly filterable sortable
retryAt
date-time
The date and time the email will rety to send. readonly filterable sortable
retryCount
number
The number of times the email has been retried to send. readonly
retryInterval
number
The amount of time in seconds between retry attempts. readonly
scheduledAt
date-time
The date and time the email is scheduled to send. filterable sortable
state
string
The current state of the mailing. Can be 'bounced', 'delivered', 'delivering', 'drafted', 'failed', 'opened', 'placeholder', 'queued', 'replied', or 'scheduled'. filterable sortable
stateChangedAt
date-time
The date and time the state last changed. readonly filterable sortable
subject
string
The subject line of the email.
trackLinks
boolean
A boolean value whether the mailing is tracking link clicks.
trackOpens
boolean
A boolean value whether the mailing is tracking email opens.
unsubscribedAt
date-time
The date and time the recepient unsubscribed from the mailing's sequence. readonly filterable sortable
updatedAt
date-time
The date and time the mailing was last updated. readonly filterable sortable
Relationship Name Description Notes
mailbox The mailbox associated with this mailing. data links
prospect The prospect associated with this mailing. data links
sequence The associated sequence. data links readonly
sequenceState The associated sequence state. data links readonly
sequenceStep The associated sequence step. data links readonly
task The associated task. data links readonly
template The template associated with this mailing. data links

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

Metadata Name Description Query Param
dataConnections The set of connections a given mailing has to external sources. provideDataConnections

Persona

A descriptor of a person, used for categorizing Prospects.

Attribute Name Description Notes
createdAt
date-time
The date and time the persona was created. readonly filterable sortable
description
string
A description of the persona.
name
string
The name of the persona (e.g. "Sales Rep"). filterable sortable
updatedAt
date-time
The date and time the persona was last updated. readonly filterable sortable
Relationship Name Description Notes
prospects The prospects with this persona. links

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

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta

Phone Number

A prospect's phone number

Attribute Name Description Notes
countryCode
string
The country code (e.g. US)
createdAt
date-time
The date and time the phone number was created. readonly
extension
string
Phone number extension (e.g. 123)
number
string
The phone number (e.g. +18889387356) filterable sortable
order
number
Ordered position in list of numbers filterable sortable
phoneType
string
Type of phone (mobile, work, home, voip, and other) filterable sortable
rawNumber
string
Unformatted phone number
status
string
The status of the number filterable sortable
statusChangedAt
date-time
Time the status was updated readonly filterable sortable
updatedAt
date-time
The date and time the phone number was last updated. readonly
Relationship Name Description Notes
prospect The owning prospect data links

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

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta

Prospect

A descriptor of a person.

Attribute Name Description Notes
addedAt
date-time
The date and time the prospect was added to any system.
addressCity
string
The prospect’s city (e.g. "Seattle").
addressCountry
string
The prospect’s country (e.g. "USA").
addressState
string
The prospect’s state (e.g. "Washington").
addressStreet
string
The prospect’s street address (e.g. "1441 N 34th St").
addressStreet2
string
The prospect’s second street address, if applicable.
addressZip
string
The prospect’s postal code (e.g. "98103").
angelListUrl
string
The prospect’s AngelList URL.
availableAt
date-time
The date and time the prospect is available to contact again.
campaignName
string
The name of the campaign the prospect is associated with.
clickCount
number
The number of clicks the prospect has made on their most recent mailing. readonly
createdAt
date-time
The date and time the prospect was created. readonly filterable sortable
custom1
string
The value of the prospect’s first custom field.
custom10
string
The value of the prospect’s 10th custom field.
custom11
string
The value of the prospect’s 11th custom field.
custom12
string
The value of the prospect’s 12th custom field.
custom13
string
The value of the prospect’s 13th custom field.
custom14
string
The value of the prospect’s 14th custom field.
custom15
string
The value of the prospect’s 15th custom field.
custom16
string
The value of the prospect’s 16th custom field.
custom17
string
The value of the prospect’s 17th custom field.
custom18
string
The value of the prospect’s 18th custom field.
custom19
string
The value of the prospect’s 19th custom field.
custom2
string
The value of the prospect’s second custom field.
custom20
string
The value of the prospect’s 20th custom field.
custom21
string
The value of the prospect’s 21st custom field.
custom22
string
The value of the prospect’s 22nd custom field.
custom23
string
The value of the prospect’s 23rd custom field.
custom24
string
The value of the prospect’s 24th custom field.
custom25
string
The value of the prospect’s 25th custom field.
custom26
string
The value of the prospect’s 26th custom field.
custom27
string
The value of the prospect’s 27th custom field.
custom28
string
The value of the prospect’s 28th custom field.
custom29
string
The value of the prospect’s 29th custom field.
custom3
string
The value of the prospect’s third custom field.
custom30
string
The value of the prospect’s 30th custom field.
custom31
string
The value of the prospect’s 31st custom field.
custom32
string
The value of the prospect’s 32nd custom field.
custom33
string
The value of the prospect’s 33rd custom field.
custom34
string
The value of the prospect’s 34th custom field.
custom35
string
The value of the prospect’s 35th custom field.
custom4
string
The value of the prospect’s fourth custom field.
custom5
string
The value of the prospect’s fifth custom field.
custom6
string
The value of the prospect’s sixth custom field.
custom7
string
The value of the prospect’s seventh custom field.
custom8
string
The value of the prospect’s eight custom field.
custom9
string
The value of the prospect’s ninth custom field.
dateOfBirth
date
The date the prospect was born.
degree
string
The degree(s) the prospect has received.
emails
email
A list of email addresses associated with the prospect. filterable
engagedAt
date-time
The date and time the prospect last engaged. readonly filterable sortable
engagedScore
number
A number representing the quality of the lead, based on the number of the prospect’s opens, clicks and mailing replies. readonly filterable sortable
eventName
string
The name of the event the prospect was met at.
externalId
string
A custom ID for the prospect, often referencing an ID in an external system.
externalOwner
string
A custom owner for the prospect, often referencing an ownering in an external system.
externalSource
string
The source of the resource’s creation (e.g. "outreach-api"). readonly filterable sortable
facebookUrl
string
The prospect’s Facebook URL.
firstName
string
The first name of the prospect. filterable sortable
gender
string
The gender of the prospect.
githubUrl
string
The prospect’s GitHub URL.
githubUsername
string
The prospect’s GitHub username. filterable sortable
googlePlusUrl
string
The prospect’s Google+ URL.
graduationDate
date
The graduation date of the prospect.
homePhones
string
A list of home phone numbers associated with the prospect.
jobStartDate
date
The starting date of the prospect’s current job.
lastName
string
The last name of the prospect. filterable sortable
linkedInConnections
number
The number of connections on the prospect’s LinkedIn profile.
linkedInId
string
The prospect’s LinkedIn ID. filterable sortable
linkedInSlug
string
The prospect’s LinkedIn slug. readonly filterable sortable
linkedInUrl
string
The prospect’s LinkedIn URL.
middleName
string
The middle name of the prospect.
mobilePhones
string
A list of mobile phone numbers associated with the prospect.
name
string
The full name of the prospect. readonly
nickname
string
The nickname of the prospect.
occupation
string
The occupation of the prospect (e.g. "Purchasing Manager").
openCount
number
The number of opens the prospect has made on their most recent mailing. readonly
optedOut
boolean
A boolean value representing whether this prospect is currently opted out of all mailings. Set this value to true to opt out the prospect; the `opted_out` timestamp will be updated to the time of the request. Set this value to false to revert the opt at and clear the opted out timestamp.
optedOutAt
date-time
The date and time the prospect opted out. readonly
otherPhones
string
A list of other phone numbers associated with the prospect.
personalNote1
string
A custom note field related to the prospect.
personalNote2
string
A second note field related to the prospect.
preferredContact
string
The preferred contact method for the prospect.
quoraUrl
string
The prospect’s Quora URL.
region
string
The primary geographic region of the prospect.
replyCount
number
The number of replies the prospect has made on their most recent mailing. readonly
school
string
The school(s) the prospect has attended.
score
number
A custom score given to measure the quality of the lead.
source
string
A custom source representing where the lead was first acquired.
specialties
string
A description of the prospect’s specialties.
stackOverflowId
string
The prospect’s StackOverflow ID. filterable sortable
stackOverflowUrl
string
The prospect’s StackOverflow URL.
tags
string
A list of tag values associated with the account (e.g. ["Interested", "2017 Expo"]). filterable
timeZone
string
The prospect’s current timezone, preferably in the IANA format (e.g. "America/LosAngeles").
timeZoneIana
string
The prospect’s current IANA timezone, if available. readonly
timeZoneInferred
string
The prospect’s current inferred IANA timezone, if available. readonly
title
string
The title of the prospect. filterable sortable
touchedAt
date-time
The date and time the prospect was last touched. readonly filterable sortable
twitterUrl
string
The prospect’s Twitter URL.
twitterUsername
string
The prospect’s Twitter username. filterable sortable
updatedAt
date-time
The date and time the prospect was last updated. readonly filterable sortable
voipPhones
string
A list of voip phone numbers associated with the prospect.
websiteUrl1
string
The URL of the prospect’s website.
websiteUrl2
string
The value of the prospect’s second website URL field.
websiteUrl3
string
The value of the prospect’s third website URL field.
workPhones
string
A list of work phone numbers associated with the prospect.
Relationship Name Description Notes
account The prospect's associated account. data links
calls The calls associated with the prospect. links
creator The creater of the prospect. data links readonly
mailings The mailings associated with the prospect. links
owner The owner of the prospect. data links
persona The persona of the prospect, if it has one. data links
phoneNumbers The prospect's phone numbers data links
sequenceStates The sequence states associated with the prospect. links
stage The stage the prospect is in. data links
tasks The tasks associated with the prospect. links
updater The most recent updater of the prospect. data links readonly

Links

instances
GET https://api.outreach.io/api/v2/prospects
create
POST https://api.outreach.io/api/v2/prospects
self
GET https://api.outreach.io/api/v2/prospects/{:id}
update
PATCH https://api.outreach.io/api/v2/prospects/{:id}
destroy
DELETE https://api.outreach.io/api/v2/prospects/{:id}

Resource Metadata

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta
dataConnections The set of connections a given prospect has to external sources. provideDataConnections

Ruleset

A reusable set of behaviors to be applied to Sequences

Attribute Name Description Notes
applyCompletedStageIn
number
The amount of time in seconds after the sequence has completed before the "completedStage" will be applied to the Prospect.
autoResumeOotoProspects
boolean
A boolean value whether out-of-the-office Prospects will be automatically resumed. See "autoResumeOotoProspectsIn" and "autoResumeOotoProspectsExpiresIn" for more information. filterable sortable
autoResumeOotoProspectsExpiresIn
number
The maximum amount of time in seconds to wait before opted-out Prospect will be resumed.
autoResumeOotoProspectsIn
number
The default amount of time in seconds to wait before opted-out Prospects will be resumed.
clicksNeededBeforeCallTaskCreated
number
The number of email clicks needed before a call task will be automatically created. This feature will be disabled unless a value is set.
createdAt
date-time
The date and time the ruleset was created. readonly filterable sortable
includeUnsubscribeLinks
boolean
A boolean value whether to include unsubscribe links within emails. filterable sortable
minimumProspectTouchedInterval
number
The minimum number of seconds that must elapse between when a Prospect was last contacted and when they may be added to a sequnce. This feature will be disabled unless a value is set.
name
string
The name of the ruleset. filterable sortable
opensNeededBeforeCallTaskCreated
number
The number of email opens needed before a call task will be automatically created. This feature will be disabled unless a value is set.
permitDuplicateProspects
string
A value determining whether a Prospect may be added to this Sequence multiple times or not. Permitted values include "allow", "disallow" (the default) and "only_if_inactive", which indicates that Prospects may be re-added to this sequence if their existing SequenceState is inactive. filterable sortable
sequenceExclusivity
string
A value determining whether Prospects may be added to multiple different Sequences. Permitted values include "all_sequences", "exclusive_sequences" and "none" (the default). If the value is "all_sequences", then Prospects may only be added if they are not active in any other Sequence; likewise, a Prospect active in a Sequence with "all_sequences" exclusivity cannot be added to any other Sequence. If the value is "exclusive_sequences", then Prospects may only be added if they are not active in any other Sequence with "exclusive_sequences" exclusivity; likewise, a Prospect active in a Sequence with "exclusive_sequences" exclusivity cannot be added to any other Sequence with "exclusive_sequences" exclusivity. If the value is "none", then no additional restrictions will be applied. filterable sortable
updatedAt
date-time
The date and time the ruleset was last updated. readonly filterable sortable
Relationship Name Description Notes
bouncedStage The stage to assign to the prospect when a mailing in this sequence bounces. data links
callTaskPriority Deprecated. This relationship exists to maintain backward compatibility and is strictly an alias for "callTaskPriorityFromOpens". data links
callTaskPriorityFromClicks The task priority to use when creating call tasks based on mail clicks. data links
callTaskPriorityFromOpens The task priority to use when creating call tasks based on mail opens. data links
completedStage The stage to assign to the prospect when this sequence completes. data links
deliveredStage The stage to assign to the prospect when a mailing in this sequence is delivered. data links
finishedStage The stage to assign to the prospect when this sequence finishes. data links
optedOutStage The stage to assign to the prospect when they opt out of this sequence. data links
owner The owner of the ruleset. data links
repliedStage The stage to assign to the prospect when a mailing in this sequence is replied to. data links
sequences The sequences associated with this ruleset. links
startedStage The stage to assign to the prospect when this sequence starts. data links

Links

instances
GET https://api.outreach.io/api/v2/rulesets
create
POST https://api.outreach.io/api/v2/rulesets
self
GET https://api.outreach.io/api/v2/rulesets/{:id}
update
PATCH https://api.outreach.io/api/v2/rulesets/{:id}
destroy
DELETE https://api.outreach.io/api/v2/rulesets/{:id}

Resource Metadata

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta

Sequence State

A descriptor of a currently sequenced prospect, which includes relationships to its sequence, prospect and user.

Attribute Name Description Notes
activeAt
date-time
The date and time the sequence state was last active. readonly
bounceCount
number
The total count of bounced mailings during this sequence state. readonly
callCompletedAt
date-time
The date and time the sequence state last had a call completed. readonly filterable sortable
clickCount
number
The total count of clicked mailings from this sequence state. readonly filterable sortable
createdAt
date-time
The date and time the sequence state was created. readonly filterable sortable
deliverCount
number
The total count of delivered mailings from this sequence state. readonly filterable sortable
errorReason
string
The reason for the most recent error. readonly
failureCount
number
The total count of failed mailings from this sequence state. readonly
negativeReplyCount
number
The total count of negative reply mailings from this sequence state. readonly
neutralReplyCount
number
The total count of neutral reply mailings from this sequence state. readonly
openCount
number
The total count of opened mailings from this sequence state. readonly filterable sortable
optOutCount
number
The total count of opted out mailings from this sequence state. readonly
pauseReason
string
The reason for the most recent pause. readonly filterable sortable
positiveReplyCount
number
The total count of positive reply mailings from this sequence state. readonly
repliedAt
date-time
The date and time the sequence state last had a mailing reply. readonly filterable sortable
replyCount
number
The total count of replied mailings from this sequence state. readonly filterable sortable
scheduleCount
number
The total count of scheduled mailings from this sequence state. readonly
state
string
The current state of the sequence state. readonly filterable sortable
stateChangedAt
date-time
The date and time the sequence state’s state last changed. readonly filterable sortable
updatedAt
date-time
The date and time the sequence state was last updated. readonly filterable sortable
Relationship Name Description Notes
calls The calls associated with the sequence state. links
creator The creator of the sequence state. data links readonly
mailbox The mailbox to use for mailing steps. data links
mailings The mailings associated with the sequence state. links
prospect The prospect this sequence state is targeting. data links
sequence The sequence this prospect is engaged in. data links
sequenceStep The current sequence step the prospect is in. data links readonly
tasks The tasks associated with the sequence state. links

Links

instances
GET https://api.outreach.io/api/v2/sequenceStates
create
POST https://api.outreach.io/api/v2/sequenceStates
self
GET https://api.outreach.io/api/v2/sequenceStates/{:id}
destroy
DELETE https://api.outreach.io/api/v2/sequenceStates/{:id}

Resource Metadata

Metadata Name Description Query Param
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta

Sequence Step

A descriptor of a single step within an automated sequence.

Attribute Name Description Notes
bounceCount
number
The total count of bounced mailings during this sequence step. readonly
clickCount
number
The total count of clicked mailings from this sequence step. readonly
createdAt
date-time
The date and time the sequence step was created. readonly filterable sortable
date
date
The date this step will activate; only applicable to date-based sequences. filterable sortable
deliverCount
number
The total count of delivered mailings from this sequence step. readonly
displayName
string
A human-readable display name that captures the step’s type and order. readonly
failureCount
number
The total count of failed mailings from this sequence step. readonly
interval
number
The interval (in minutes) until this still will activate; only applicable to interval-based sequences.
negativeReplyCount
number
The total count of negative reply mailings from this sequence step. readonly
neutralReplyCount
number
The total count of neutral reply mailings from this sequence step. readonly
openCount
number
The total count of opened mailings from this sequence step. readonly
optOutCount
number
The total count of opted out mailings from this sequence step. readonly
order
number
The step’s display order within its sequence. filterable sortable
positiveReplyCount
number
The total count of positive reply mailings from this sequence step. readonly
replyCount
number
The total count of replied mailings from this sequence step. readonly
scheduleCount
number
The total count of scheduled mailings from this sequence step. readonly
stepType
string
The step’s type; must be "auto_email", "manual_email", "call" or "task". filterable sortable
taskNote
string
An optional note to associate with created tasks.
updatedAt
date-time
The date and time the sequence step was last updated. readonly filterable sortable
Relationship Name Description Notes
calls The calls associated with the sequence step. links
creator The creator of the sequence step. data links readonly
mailings The mailings associated with the sequence step. links
sequence The associated sequence. data links
sequenceTemplates The sequence templates in use by this sequence step. data links readonly
taskPriority The associated task priority. data links
tasks The tasks associated with the sequence step. links
updater The most recent updater of the sequence step. data links readonly

Links

instances
GET https://api.outreach.io/api/v2/sequenceSteps
create
POST https://api.outreach.io/api/v2/sequenceSteps
self
GET https://api.outreach.io/api/v2/sequenceSteps/{:id}
update
PATCH https://api.outreach.io/api/v2/sequenceSteps/{:id}
destroy
DELETE https://api.outreach.io/api/v2/sequenceSteps/{:id}

Resource Metadata

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta

Sequence Template

An object used to track which templates are in use by which sequence steps.

Attribute Name Description Notes
bounceCount
number
The total count of bounced mailings during this sequence template. readonly
clickCount
number
The total count of clicked mailings from this sequence template. readonly
createdAt
date-time
The date and time the sequence template was created. readonly
deliverCount
number
The total count of delivered mailings from this sequence template. readonly
enabled
boolean
Boolean indicating if the sequence template is currently enabled. readonly
enabledAt
date-time
Datetime for when the sequence template was enabled. readonly
failureCount
number
The total count of failed mailings from this sequence template. readonly
negativeReplyCount
number
The total count of negative reply mailings from this sequence template. readonly
neutralReplyCount
number
The total count of neutral reply mailings from this sequence template. readonly
openCount
number
The total count of opened mailings from this sequence template. readonly
optOutCount
number
The total count of opted out mailings from this sequence template. readonly
positiveReplyCount
number
The total count of positive reply mailings from this sequence template. readonly
replyCount
number
The total count of replied mailings from this sequence template. readonly
scheduleCount
number
The total count of scheduled mailings from this sequence template. readonly
updatedAt
date-time
The date and time the sequence template was last updated. readonly
Relationship Name Description Notes
creator User that created the sequence template. data links readonly
sequenceStep The sequence step that uses the sequence template. data links
template The template used for this sequence template. data links
updater User that last updated the sequence template. data links readonly

Links

instances
GET https://api.outreach.io/api/v2/sequenceTemplates
create
POST https://api.outreach.io/api/v2/sequenceTemplates
self
GET https://api.outreach.io/api/v2/sequenceTemplates/{:id}
update
PATCH https://api.outreach.io/api/v2/sequenceTemplates/{:id}
destroy
DELETE https://api.outreach.io/api/v2/sequenceTemplates/{:id}

Resource Metadata

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta

Sequence

Leverage emailing within Sequences to engage each individual persona more effectively, and queue up the right actions at the right time.

Attribute Name Description Notes
bounceCount
number
The total count of bounced mailings during this sequence. readonly
clickCount
number
The total count of clicked mailings from this sequence. readonly filterable sortable
createdAt
date-time
The date and time the sequence was created. readonly filterable sortable
deliverCount
number
The total count of delivered mailings from this sequence. readonly filterable sortable
description
string
A custom description for the sequence.
enabled
boolean
A boolean value determining whether the sequence is enabled or not. readonly
enabledAt
date-time
The date and time the sequence was enabled, or null if currently disabled. readonly filterable sortable
failureCount
number
The total count of failed mailings from this sequence. readonly
finishOnReply
boolean
A boolean value determining whether a mailing reply should mark that prospect as finished.
lastUsedAt
date-time
The date and time the sequence was last used. readonly filterable sortable
locked
boolean
A boolean value determining whether the sequence is locked or not. readonly
lockedAt
date-time
The date and time the sequence was locked, or null if currently unlocked. readonly filterable sortable
maxActivations
number
The maximum number of prospects that can be associated with the sequence. Only applies if the sequence type is "date".
name
string
The name or the sequence. filterable sortable
negativeReplyCount
number
The total count of negative reply mailings from this sequence. readonly
neutralReplyCount
number
The total count of neutral reply mailings from this sequence. readonly
openCount
number
The total count of opened mailings from this sequence. readonly filterable sortable
optOutCount
number
The total count of opted out mailings from this sequence. readonly
positiveReplyCount
number
The total count of positive reply mailings from this sequence. readonly
replyCount
number
The total count of replied mailings from this sequence. readonly filterable sortable
scheduleCount
number
The total count of scheduled mailings from this sequence. readonly
scheduleIntervalType
string
The schedule interval type must be either "calendar" or "schedule"
sequenceType
string
The sequence type must be either "date" or "interval".
shareType
string
The sequence share type must be either "private", "read_only" or "shared". filterable sortable
tags
string
A list of tag values associated with the sequence (e.g. ["Tier 1", "Inbound Leads"]) filterable
throttleMaxAddsPerDay
number
The maximum number of associated sequence states per user mailbox that can be advanced each day. filterable sortable
throttlePaused
boolean
A boolean value determining whether the throttling of sequence states is paused or not.
throttlePausedAt
date-time
The date and time the sequence state throttling was paused, or null if not currently paused. readonly
updatedAt
date-time
The date and time the sequence was last updated. readonly filterable sortable
Relationship Name Description Notes
calls The associated calls. links
creator The creater of the sequence. data links readonly
mailings The associated mailings. links
owner The owner of the sequence. data links
ruleset The associated ruleset. data links
sequenceStates The associated sequence states. links
sequenceSteps The associated sequence steps. data links
tasks The associated tasks. links
updater The most recent updater of the sequence. data links readonly

Links

instances
GET https://api.outreach.io/api/v2/sequences
create
POST https://api.outreach.io/api/v2/sequences
self
GET https://api.outreach.io/api/v2/sequences/{:id}
update
PATCH https://api.outreach.io/api/v2/sequences/{:id}
destroy
DELETE https://api.outreach.io/api/v2/sequences/{:id}

Resource Metadata

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta

Snippet

A piece of an email to be reused in multiple messages.

Attribute Name Description Notes
bodyHtml
string
The HTML of the snippet.
bodyText
string
The text of the snippet. readonly
createdAt
date-time
The date and time the snippet was created. readonly filterable sortable
name
string
The name of the snippet. filterable sortable
shareType
string
The permissions for sharing the snippet; must be "private" or "shared." filterable sortable
tags
string
A list of tags associated with the snippet (e.g. ["Useful", "Prospecting"]). filterable
updatedAt
date-time
The date and time the snippet was last updated. readonly filterable sortable
Relationship Name Description Notes
creator The creator of the snippet. data links readonly
owner The owner of the snippet. data links
updater The updater of the snippet. data links readonly

Links

instances
GET https://api.outreach.io/api/v2/snippets
create
POST https://api.outreach.io/api/v2/snippets
self
GET https://api.outreach.io/api/v2/snippets/{:id}
update
PATCH https://api.outreach.io/api/v2/snippets/{:id}
destroy
DELETE https://api.outreach.io/api/v2/snippets/{:id}

Resource Metadata

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta

Stage

A descriptor of the point in the process, used for categorizing Prospects.

Attribute Name Description Notes
color
string
The color the stage label will be highlighted in the interface, specified as a hexidecimal value (e.g. "#5951ff").
createdAt
date-time
The date and time the stage was created. readonly filterable sortable
name
string
The name of the stage (e.g. "Qualified Lead"). filterable sortable
order
number
The stage's display order within the collection. filterable sortable
updatedAt
date-time
The date and time the stage was last updated. readonly filterable sortable
Relationship Name Description Notes
creator The creator of the stage. data links readonly
prospects The prospects associated to the stage. links
updater The most recent updater of the stage. data links readonly

Links

instances
GET https://api.outreach.io/api/v2/stages
create
POST https://api.outreach.io/api/v2/stages
self
GET https://api.outreach.io/api/v2/stages/{:id}
update
PATCH https://api.outreach.io/api/v2/stages/{:id}
destroy
DELETE https://api.outreach.io/api/v2/stages/{:id}

Resource Metadata

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta
dataConnections The set of connections a given stage has to external sources. provideDataConnections

Task Priority

A descriptor of importance used for categorizing Tasks.

Attribute Name Description Notes
color
number
The color the task priority label will be highlighted in the interface, specified as a hexadecimal value (e.g. "0xFF5951FF").
createdAt
date-time
The date and time the task priority was created. readonly filterable sortable
name
string
The name of the task priority (e.g. "High"). filterable sortable
updatedAt
date-time
The date and time the task priority was last updated. readonly filterable sortable
weight
number
A relative value used for display order. Task priorities are listed from lowest to highest weight.
Relationship Name Description Notes
sequenceSteps The associated sequence steps. links
tasks The associated tasks. links

Links

instances
GET https://api.outreach.io/api/v2/taskPriorities
self
GET https://api.outreach.io/api/v2/taskPriorities/{:id}

Task

An item that requires action to complete.

Attribute Name Description Notes
action
string
The action type of the task. Can be 'action_item', 'call', 'email', or 'in_person'. filterable sortable
completed
boolean
A boolean value whether the task has been completed. readonly
completedAt
date-time
The date and time the task was completed. readonly
createdAt
date-time
The date and time the task was created. readonly filterable sortable
dueAt
date-time
The date and time the task is due. filterable sortable
note
string
An optional note for the task.
scheduledAt
date-time
The date and time the pending task is scheduled for. readonly filterable sortable
state
string
The current state of the task. Can be 'pending', 'incomplete', or 'complete'. readonly filterable sortable
stateChangedAt
date-time
The date and time the state last changed. readonly filterable sortable
taskType
string
The type of task. Can be 'follow_up', 'manual', 'no_reply', 'sequence_open', 'sequence_click', 'sequence_step_call', 'sequence_step_email', 'sequence_step_task', or 'touch'. Tasks created through the API will automatically be 'manual' tasks. readonly filterable sortable
updatedAt
date-time
The date and time the task was last updated. readonly filterable sortable
Relationship Name Description Notes
account The associated account. data links readonly
call The associated call, if a call task. data links readonly
calls The associated calls, if a call task. links
completer The completer of this task. data links readonly
creator The creator of this task. data links readonly
mailing The associated mailing, if a mailing task. data links readonly
mailings The associated mailings, if a mailing task. links
owner The owner of this task. data links
prospect The associated prospect. data links readonly
sequence The associated sequence. data links readonly
sequenceState The associated sequence state. data links readonly
sequenceStep The associated sequence step. data links readonly
subject The task's subject, either an account or prospect. data links
taskPriority The associated task priority. data links
template The associated template. data links readonly

Member Actions

mark_complete

Marks the task as complete.

Parameter name Description
completionNote
A note to attach to the associated prospect, if there is one.
completionAction
For sequence step tasks, this specifies how to finish the sequence state. Possible values are: 'finish_no_reply' to finish the sequence, 'finish_replied' to set the sequence as replied, and anything else (including leaving it blank) will advance the sequence state.
snooze

Sets the `dueAt` value to be a day later than either now or the existing `dueAt` value, whichever is later.

advance

Advances the sequence state associated with the task.

deliver

Schedules the mailing associated with the task for delivery, if possible.

Links

instances
GET https://api.outreach.io/api/v2/tasks
create
POST https://api.outreach.io/api/v2/tasks
self
GET https://api.outreach.io/api/v2/tasks/{:id}
destroy
DELETE https://api.outreach.io/api/v2/tasks/{:id}
mark_complete
POST https://api.outreach.io/api/v2/tasks/{:id}/actions/markComplete
snooze
POST https://api.outreach.io/api/v2/tasks/{:id}/actions/snooze
advance
POST https://api.outreach.io/api/v2/tasks/{:id}/actions/advance
deliver
POST https://api.outreach.io/api/v2/tasks/{:id}/actions/deliver

Resource Metadata

Metadata Name Description Query Param
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta
dataConnections The set of connections a given task has to external sources. provideDataConnections

Team

A descriptor of a group of users.

Attribute Name Description Notes
color
string
The color used to label and highlight the team.
createdAt
date-time
The date and time the team was created. readonly
name
string
The name of the team (e.g. "SDRs").
updatedAt
date-time
The date and time the team was last updated. readonly
Relationship Name Description Notes
creator The creator of the team. data links readonly
updater The most recent updater of the team. data links readonly
users The users associated with the team. links readonly

Links

instances
GET https://api.outreach.io/api/v2/teams
create
POST https://api.outreach.io/api/v2/teams
self
GET https://api.outreach.io/api/v2/teams/{:id}
update
PATCH https://api.outreach.io/api/v2/teams/{:id}
destroy
DELETE https://api.outreach.io/api/v2/teams/{:id}

Resource Metadata

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta

Template

A reusable template for building emails.

Attribute Name Description Notes
archived
boolean
Boolean value indicating if the template has been archived.
archivedAt
date-time
The date and time the template was archived. readonly filterable sortable
bccRecipients
string
A list of default person and email address pairs to receive this template in the "bcc" field (e.g. ["Billy Bob <billy.bob@seattle.city>"])
bodyHtml
string
The body HTML of the template.
bodyText
string
The body text of the template. readonly
bounceCount
number
The total count of bounced mailings during this template. readonly
ccRecipients
string
A list of default person and email address pairs to receive this template in the "cc" field (e.g. ["Billy Bob <billy.bob@seattle.city>"])
clickCount
number
The total count of clicked mailings from this template. readonly filterable sortable
createdAt
date-time
The date and time the template was created. readonly filterable sortable
deliverCount
number
The total count of delivered mailings from this template. readonly filterable sortable
failureCount
number
The total count of failed mailings from this template. readonly
lastUsedAt
date-time
The last time the template was used. readonly filterable sortable
name
string
The name of the template. filterable sortable
negativeReplyCount
number
The total count of negative reply mailings from this template. readonly
neutralReplyCount
number
The total count of neutral reply mailings from this template. readonly
openCount
number
The total count of opened mailings from this template. readonly filterable sortable
optOutCount
number
The total count of opted out mailings from this template. readonly
positiveReplyCount
number
The total count of positive reply mailings from this template. readonly
replyCount
number
The total count of replied mailings from this template. readonly filterable sortable
scheduleCount
number
The total count of scheduled mailings from this template. readonly
shareType
string
The share type must be one of "read_only," "private," or "shared". filterable sortable
subject
string
The subject line for the email to be sent.
tags
string
A list of tag values associated with the template (e.g. ["Sequencing", "Quick Response"]). filterable
toRecipients
string
A list of default person and email address pairs to receive this template in the "to" field (e.g. ["Billy Bob <billy.bob@seattle.city>"])
trackLinks
boolean
Boolean value indicating if link tracking is on for the template.
trackOpens
boolean
Boolean value indicating if open tracking is on for the template.
updatedAt
date-time
The date and time the template was last updated. readonly filterable sortable
Relationship Name Description Notes
creator The creator of the template. data links readonly
owner The owner of the template. data links
sequenceTemplates The sequence templates using the template for their content. data links readonly
updater The creator of the template. data links readonly

Links

instances
GET https://api.outreach.io/api/v2/templates
create
POST https://api.outreach.io/api/v2/templates
self
GET https://api.outreach.io/api/v2/templates/{:id}
update
PATCH https://api.outreach.io/api/v2/templates/{:id}
destroy
DELETE https://api.outreach.io/api/v2/templates/{:id}

Resource Metadata

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta

User

The individual that uses the application. See https://api.outreach.io/api/v2/docs#invite-new-users for more information on inviting new users.

Attribute Name Description Notes
activityNotificationsDisabled
boolean
A boolean value whether the user's activity notifications are disabled.
bounceWarningEmailEnabled
boolean
A boolean value whether the user's bounce warning emails are enabled.
bridgePhone
string
The telephone number of the user's bridge phone.
bridgePhoneExtension
string
The extension number of the user's bridge phone.
createdAt
date-time
The date and time the user was created. readonly filterable sortable
custom1
string
The value of the user's first custom field.
custom2
string
The value of the user's second custom field.
custom3
string
The value of the user's third custom field.
custom4
string
The value of the user's fourth custom field.
custom5
string
The value of the user's fifth custom field.
dailyDigestEmailEnabled
boolean
A boolean value whether the user's daily digest emails are enabled.
duties
object
A collection of the user's work roles.
email
email
The email address of the user. filterable sortable
enableVoiceRecordings
boolean
A boolean value whether the user has voice recordings enabled.
firstName
string
The first name of the user. filterable sortable
inboundBridgePhone
string
The telephone number of the user's inbound bridge phone.
inboundBridgePhoneExtension
string
The extension number of the user's inbound bridge phone.
inboundCallBehavior
string
The behavior of inbound calls. Must be either "inbound_bridge" or "inbound_voicemail".
inboundVoicemailCustomMessageText
string
The message for inbound voicemails (e.g. "Please leave a message and I will get back to you as soon I can").
inboundVoicemailMessageTextVoice
string
The gender of the voice that reads the voicemail message. Must be either "man" or "woman".
lastName
string
The last name of the user. filterable sortable
lastSignInAt
date-time
The date and time the user last signed in. readonly
locked
boolean
A boolean value whether the user is locked out of the application.
mailboxErrorEmailEnabled
boolean
A boolean value whether the user's mailbox error emails are enabled.
name
string
The full name of the user. readonly
notificationsEnabled
boolean
A boolean value whether the user's notifications are enabled.
passwordExpiresAt
date-time
The date and time the current password expires. readonly
phoneCountryCode
string
The country code of the user's phone.
phoneNumber
string
The telephone number of the user's phone.
phoneType
string
The user's type of telephone. Must be either "bridge" or "voip".
prefersLocalPresence
boolean
A boolean value whether the user prefers that a voice call comes from a local phone number.
senderNotificationsExcluded
boolean
A boolean value whether the user's sender notifications are excluded.
taskNotificationsEnabled
boolean
A boolean value whether the user's task notifications are enabled.
title
string
The user's job title (e.g. "Staff Accountant").
unknownReplyEmailEnabled
boolean
A boolean value whether the user's unknown reply emails are enabled.
updatedAt
date-time
The date and time the user was last updated. readonly filterable sortable
username
string
A reader friendly unique identifier of the user. filterable sortable
weeklyDigestEmailEnabled
boolean
A boolean value whether the user's weekly digest email are enabled.
Relationship Name Description Notes
calendar The calendar associated with the user. data links readonly
creator The creator of the user. data links readonly
mailbox The mailbox associated with the user. data links readonly
teams The teams the user belongs to. data links
updater The most recent updater of the user. data links readonly

Links

instances
GET https://api.outreach.io/api/v2/users
create
POST https://api.outreach.io/api/v2/users
self
GET https://api.outreach.io/api/v2/users/{:id}
update
PATCH https://api.outreach.io/api/v2/users/{:id}

Resource Metadata

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
dataConnections The set of connections a given user has to external sources. provideDataConnections

Webhook

A configurable notification that submits external JSON-API-formatted HTTP requests whenever resources are modified.

Attribute Name Description Notes
action
string
The action that will trigger this webhook (e.g. "*", "created", "updated", "destroyed"). Webhooks will only execute if both the action and resource match. filterable sortable
active
boolean
A boolean value indicating whether the webhook is active. filterable sortable
createdAt
date-time
The date and time the webhook was created. readonly
resource
string
The resource that will trigger this webhook (e.g. "*", "prospect", "sequenceState"). Webhooks will only execute if both the action and resource match. filterable sortable
secret
string
A private token used to verify the authenticity of incoming webhook payloads.
updatedAt
date-time
The date and time the webhook was last updated. readonly
url
string
The URL where the webhook will route its POST HTTP request.
Relationship Name Description Notes
authorizer The authorizer of the webhook. The webhook will not deliver results if the authorizer does not have permission to read the resource being returned. data links readonly
creator The creator of the webhook. data links readonly
updater The most recent updater of the webhook. data links readonly

Links

instances
GET https://api.outreach.io/api/v2/webhooks
create
POST https://api.outreach.io/api/v2/webhooks
self
GET https://api.outreach.io/api/v2/webhooks/{:id}
update
PATCH https://api.outreach.io/api/v2/webhooks/{:id}
destroy
DELETE https://api.outreach.io/api/v2/webhooks/{:id}

Resource Metadata

Metadata Name Description Query Param
canWrite A boolean value indicating whether the current API user has write access to this resource. provideAuthorizationMeta
canDelete A boolean value indicating whether the current API user has delete access to this resource. provideAuthorizationMeta