A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Outreach API is how an app or AI agent works with an Outreach instance: creating a prospect, adding that prospect to a sequence, sending a mailing, or logging a call or task. Access is granted through an OAuth token whose scopes name each resource and the level of access, read, write, delete, or all, so a token reaches only the resources it was granted. Outreach can also push an event to a registered URL when something changes, like a prospect being created or an email being opened.
How an app or AI agent connects to Outreach determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes Outreach tools to agents, and each is governed by the token behind it and the permissions that token carries.
The REST API follows the JSON:API 1.0 specification at https://api.outreach.io/api/v2. A request sends and accepts the application/vnd.api+json content type, and a request without it is rejected. Resources carry a type, attributes, and relationships, and lists support filtering, sorting, sparse fieldsets, and including related resources. A call authenticates with an OAuth 2.0 bearer token whose scopes set which resources it can read or write.
A hosted Model Context Protocol server at https://api.outreach.io/mcp exposes Outreach tools to AI agents and MCP clients. It is generally available and authenticates each user with OAuth, requiring a client that supports OAuth 2.1 and Dynamic Client Registration. It exposes tools across prospecting, accounts, sequences, deals, users, and meetings, like prospect lookup, search, create, and delete. It requires the Amplify add-on on the user's plan.
Outreach POSTs an event to an HTTPS URL registered through the webhooks resource. A webhook can be scoped to a resource and an action, like prospect and created, or use a wildcard to receive everything. The receiver gets a payload describing what changed, so an integration reacts to activity without polling.
An integration redirects a user to https://api.outreach.io/oauth/authorize, requests a set of scopes, and exchanges the returned code at https://api.outreach.io/oauth/token for an access token. Scopes are period-separated, a pluralized resource name plus an access token of read, write, delete, or all, like prospects.read or sequenceStates.write. Scopes are not additive, so prospects.write does not grant read.
Because an access token expires after 2 hours, an integration exchanges a refresh token at the token endpoint for a new access token without sending the user through sign-in again. A refresh token stays valid for 14 days, and a user and application pair can hold up to 100 refresh tokens at once.
A server-to-server token represents the application rather than a user, and is issued per organization installation. The app signs a JWT with its private key to fetch a setup token and installation id, then exchanges those for the token. It carries scopes the same way as user tokens and stays valid for one hour, with no refresh, so a new one is requested as needed.
The Outreach API is split into areas an agent can act on, like prospects, accounts, sequences, mailings, calls, and tasks. Each area has its own methods and its own permission, and a write in some areas sends real email or moves a prospect through a sequence.
Methods for working with prospects, the people an agent reaches out to.
Methods for working with accounts, the companies prospects belong to.
Methods for working with sequences, the multi-step outreach campaigns.
Methods for placing a prospect into a sequence and tracking its progress.
Methods for working with mailings, the individual emails sent to prospects.
Methods for working with logged calls to prospects.
Methods for working with tasks, the to-dos that drive rep activity.
Methods for working with email templates used in outreach.
Methods for reading the people in an Outreach instance.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ProspectsMethods for working with prospects, the people an agent reaches out to.5 | ||||||
| GET | /api/v2/prospects | List prospects, with filtering, sorting, and sparse fieldsets. | read | prospects.read | Current | |
Read-only. The prospects.all scope also grants read. Acts onprospect Permission (capability) prospects.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/prospects/{id} | Retrieve a single prospect by id. | read | prospects.read | Current | |
Read-only. Acts onprospect Permission (capability) prospects.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/prospects | Create a prospect, the person an outreach campaign targets. | write | prospects.write | Current | |
The prospects.write scope does not grant read; use prospects.all for both. Acts onprospect Permission (capability) prospects.writeVersionAvailable since the API’s base version Webhook event prospect.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/prospects/{id} | Update a prospect's attributes or relationships. | write | prospects.write | Current | |
A core write. Acts onprospect Permission (capability) prospects.writeVersionAvailable since the API’s base version Webhook event prospect.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/prospects/{id} | Delete a prospect. | write | prospects.delete | Current | |
Delete is a separate token from write; prospects.all also grants it. Acts onprospect Permission (capability) prospects.deleteVersionAvailable since the API’s base version Webhook event prospect.destroyedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AccountsMethods for working with accounts, the companies prospects belong to.4 | ||||||
| GET | /api/v2/accounts | List accounts, the companies prospects belong to. | read | accounts.read | Current | |
Read-only. The accounts.all scope also grants read. Acts onaccount Permission (capability) accounts.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/accounts/{id} | Retrieve a single account by id. | read | accounts.read | Current | |
Read-only. Acts onaccount Permission (capability) accounts.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/accounts | Create an account record. | write | accounts.write | Current | |
The accounts.write scope does not grant read; use accounts.all for both. Acts onaccount Permission (capability) accounts.writeVersionAvailable since the API’s base version Webhook event account.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/accounts/{id} | Update an account's attributes or relationships. | write | accounts.write | Current | |
A core write. Acts onaccount Permission (capability) accounts.writeVersionAvailable since the API’s base version Webhook event account.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SequencesMethods for working with sequences, the multi-step outreach campaigns.3 | ||||||
| GET | /api/v2/sequences | List sequences, the multi-step outreach campaigns. | read | sequences.read | Current | |
Read-only. The sequences.all scope also grants read. Acts onsequence Permission (capability) sequences.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/sequences/{id} | Retrieve a single sequence by id. | read | sequences.read | Current | |
Read-only. Acts onsequence Permission (capability) sequences.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/sequences | Create a sequence definition. | write | sequences.write | Current | |
The sequences.write scope does not grant read; use sequences.all for both. Acts onsequence Permission (capability) sequences.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Sequence statesMethods for placing a prospect into a sequence and tracking its progress.3 | ||||||
| GET | /api/v2/sequenceStates | List sequence states, each one a prospect's place in a sequence. | read | sequenceStates.read | Current | |
Read-only. The sequenceStates.all scope also grants read. Acts onsequenceState Permission (capability) sequenceStates.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/sequenceStates | Add a prospect to a sequence by creating a sequence state, referencing the prospect, the sequence, and a mailbox. | write | sequenceStates.write | Current | |
This is how outreach to a prospect starts; the new state begins active on the first step. Acts onsequenceState Permission (capability) sequenceStates.writeVersionAvailable since the API’s base version Webhook event sequenceState.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/sequenceStates/{id}/actions/finish | Finish a sequence state, removing the prospect from the sequence. | write | sequenceStates.write | Current | |
An action endpoint; stops further steps for that prospect. Acts onsequenceState Permission (capability) sequenceStates.writeVersionAvailable since the API’s base version Webhook event sequenceState.finishedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MailingsMethods for working with mailings, the individual emails sent to prospects.3 | ||||||
| GET | /api/v2/mailings | List mailings, the individual emails sent to prospects. | read | mailings.read | Current | |
Read-only. The mailings.all scope also grants read. Acts onmailing Permission (capability) mailings.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/mailings/{id} | Retrieve a single mailing by id, including its open and reply state. | read | mailings.read | Current | |
Read-only. Acts onmailing Permission (capability) mailings.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/mailings | Create a mailing, an email scheduled or sent to a prospect. | write | mailings.write | Current | |
A write here can result in a real email being sent. Acts onmailing Permission (capability) mailings.writeVersionAvailable since the API’s base version Webhook event mailing.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CallsMethods for working with logged calls to prospects.2 | ||||||
| GET | /api/v2/calls | List calls logged against prospects. | read | calls.read | Current | |
Read-only. The calls.all scope also grants read. Acts oncall Permission (capability) calls.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/calls | Log a call against a prospect. | write | calls.write | Current | |
The calls.write scope does not grant read; use calls.all for both. Acts oncall Permission (capability) calls.writeVersionAvailable since the API’s base version Webhook event call.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TasksMethods for working with tasks, the to-dos that drive rep activity.3 | ||||||
| GET | /api/v2/tasks | List tasks, the to-dos that drive rep activity. | read | tasks.read | Current | |
Read-only. The tasks.all scope also grants read. Acts ontask Permission (capability) tasks.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/tasks | Create a task for a user to action. | write | tasks.write | Current | |
The tasks.write scope does not grant read; use tasks.all for both. Acts ontask Permission (capability) tasks.writeVersionAvailable since the API’s base version Webhook event task.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/tasks/{id} | Update a task, for example to complete it. | write | tasks.write | Current | |
Completing a task fires task.completed. Acts ontask Permission (capability) tasks.writeVersionAvailable since the API’s base version Webhook event task.completedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TemplatesMethods for working with email templates used in outreach.2 | ||||||
| GET | /api/v2/templates | List email templates used in outreach. | read | templates.read | Current | |
Read-only. The templates.all scope also grants read. Acts ontemplate Permission (capability) templates.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/templates | Create an email template for reuse across outreach. | write | templates.write | Current | |
The templates.write scope does not grant read; use templates.all for both. Acts ontemplate Permission (capability) templates.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersMethods for reading the people in an Outreach instance.2 | ||||||
| GET | /api/v2/users | List the users in an Outreach instance. | read | users.read | Current | |
Returns names, email addresses, and roles. The users.all scope also grants read. Acts onuser Permission (capability) users.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/users/{id} | Retrieve a single user by id. | read | users.read | Current | |
Read-only. Acts onuser Permission (capability) users.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Outreach can notify an app when something happens in the platform, like a prospect being created or an email being delivered, opened, or replied to. It posts an event describing the change to a registered HTTPS URL, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
prospect.created | A new prospect was created. | /api/v2/prospects |
prospect.updated | A prospect's attributes or relationships changed. | /api/v2/prospects/{id} |
prospect.destroyed | A prospect was deleted. | /api/v2/prospects/{id} |
account.created | A new account was created. | /api/v2/accounts |
account.updated | An account's attributes or relationships changed. | /api/v2/accounts/{id} |
sequenceState.created | A prospect was added to a sequence and outreach began. | /api/v2/sequenceStates |
sequenceState.finished | A prospect finished or was removed from a sequence. | /api/v2/sequenceStates/{id}/actions/finish |
mailing.created | A mailing was created and scheduled or sent. | /api/v2/mailings |
call.created | A call was logged against a prospect. | /api/v2/calls |
task.created | A task was created. | /api/v2/tasks |
task.completed | A task was completed. | /api/v2/tasks/{id} |
Outreach limits how fast an app can call, through an hourly request quota counted per user. Each response reports how much of the quota is left, and going over returns a clear error with a reset time.
Outreach meters requests per user, not per method, allowing 10,000 requests per hour for each user a token acts for. Every response carries three headers: X-RateLimit-Limit is the ceiling for the period, X-RateLimit-Remaining is how many requests are left, and X-RateLimit-Reset (also sent as Retry-After) is when the counter resets. Going over returns HTTP 429 with a JSON error. Some endpoints, like the bulk API, apply their own special rules.
Lists are cursor-paginated by default: page[size] sets the page size, and the response links object carries first, prev, and next URLs to walk through pages. Adding count=false skips counting the total and improves performance on large lists. An older offset model using page[offset] and page[limit] is deprecated; it caps the offset at 10,000 and the limit at 1,000.
A request must send the application/vnd.api+json content type or it is rejected with 415. On the deprecated offset model, page[limit] may be at most 1,000 and page[offset] at most 10,000. A response can be trimmed with sparse fieldsets, requesting only named attributes per resource type with the fields parameter.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | No valid access token was provided, or the token has expired. | Refresh the access token at the token endpoint, or send the user back through OAuth, then resend. |
| 403 | Forbidden | The token is valid but its scopes do not cover this request, for example a read-only scope on a write. | Request the resource's write, delete, or all scope and have the user re-authorize. |
| 404 | Not Found | The requested resource does not exist or is not visible to this token. | Verify the resource id and that the token's user can see it. |
| 415 | Unsupported Media Type | The request was sent without the application/vnd.api+json content type that the JSON:API requires. | Set the Content-Type header to application/vnd.api+json and resend. |
| 422 | Unprocessable Entity | The request was well-formed but a validation rule failed, for example a missing required attribute or relationship. | Read the errors array, where each entry carries a title, detail, and a source pointer to the offending field, then fix and resend. |
| 429 | Too Many Requests | The per-user hourly request quota was exceeded. | Wait until the X-RateLimit-Reset time, then resend. Spread requests to stay under the quota. |
Outreach runs a single, continuously updated version of its API, and ships dated deprecation notices when a behavior is changing or being removed, with a grace period before it takes effect.
Outreach runs a single, continuously updated version 2 of its REST API, following the JSON:API 1.0 specification. There is no dated version string to pin; instead, behavior changes are announced as dated deprecation notices with a grace period before they take effect.
The API stopped counting the total number of matching resources on a list by default. Applications registered after 13 October 2024 had to opt in, and existing applications were given a grace period until 12 February 2025, after which a query that needs a total must add count=true.
The original Audit API was deprecated in September 2024 and replaced by a new Audit Log API.
Three behaviors were deprecated effective 31 October 2023: sorting by relationship attributes, filtering by relationship attributes, and including related objects in create and update responses.
Track the deprecation notices and move off a removed behavior before its effective date.
Outreach API deprecations ↗Bollard AI sits between a team's AI agents and Outreach. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.