A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Salesloft API is how an app or AI agent works with a Salesloft workspace: reading and updating people and the accounts they belong to, adding a person to a cadence, logging calls and tasks, and reading sent emails. Access is granted through a Bearer token, where documented scopes narrow what can be read, while many writes carry no scope and instead inherit whatever the token's user is allowed to do. Salesloft can also push an event to a subscribed URL when something changes, like a person being created or a task being completed.
How an app or AI agent connects to Salesloft determines what it can reach. There is a route for making calls and a route for receiving events, each governed by the token behind it and what that token's user is allowed to do.
The REST API answers at https://api.salesloft.com/v2 with JSON responses and offset-based paging. A call authenticates with a Bearer token in the Authorization header. The current version is v2, with a legacy v1 still served for older integrations.
Salesloft POSTs the changed object to a subscribed callback URL when an event fires, such as person_created or task_completed. A subscription is created through the API for one event type and URL, and the required scope depends on the event type. The payload is signed so the receiver can confirm it came from Salesloft.
A user approves the application, which exchanges an authorization code for a 2-hour access token and a refresh token. The token is sent as 'Authorization: Bearer
A server-to-server flow where the application authenticates as itself, with no end user approving each time. Salesloft recommends it for background tasks and system-wide integrations. It still authenticates with a Bearer token and is bound by the scopes the application holds.
A personal API key calls the API on behalf of the user who issued it, sent as a Bearer token. It is the quickest route for a single-user script, and it reaches whatever that user can reach.
The Salesloft API is split into areas an agent can act on, like people, accounts, cadences, emails, calls, and tasks. Each area has its own methods, and writes here change real prospect records or move people through outreach.
List, read, create, update, and delete the people (prospects) a team is working.
List, read, create, and update the company accounts that people belong to.
List and read the cadences (outreach sequences) a team runs.
List and read who is on which cadence, and add a person to a cadence.
List and read sent emails and their tracking detail.
List, read, and log calls against people.
List, read, create, and update the tasks a rep works through.
List, read, create, and update notes attached to people and accounts.
Read the authenticated user, and list and read the team's users.
List and read webhook subscriptions, and create one to receive events.
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 | |
|---|---|---|---|---|---|---|
PeopleList, read, create, update, and delete the people (prospects) a team is working.5 | ||||||
| GET | /v2/people | List people on the team, with filtering, paging, and sorting. | read | people:read | Current | |
Reading people needs the people:read scope on the token. Acts onperson Permission (capability) people:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/people/{id} | Fetch a single person by id. | read | people:read | Current | |
Reading a person needs the people:read scope on the token. Acts onperson Permission (capability) people:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/people | Create a person. Either an email address, or a phone and last name, must be given as a unique lookup on the team. | write | — | Current | |
No specific scope is documented for this write, so any valid token whose user can create people may call it. The documented people scope, people:read, covers reads. Acts onperson Permission (capability)None required VersionAvailable since the API’s base version Webhook event person_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/people/{id} | Update an existing person. | write | — | Current | |
No specific scope is documented for this write, so any valid token whose user can edit the person may call it. Acts onperson Permission (capability)None required VersionAvailable since the API’s base version Webhook event person_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/people/{id} | Delete a person. | write | — | Current | |
No specific scope is documented for this write. Deletion is irreversible. Acts onperson Permission (capability)None required VersionAvailable since the API’s base version Webhook event person_deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AccountsList, read, create, and update the company accounts that people belong to.4 | ||||||
| GET | /v2/accounts | List accounts on the team, with filtering, paging, and sorting. | read | accounts:read | Current | |
Reading accounts needs the accounts:read scope on the token. Acts onaccount Permission (capability) accounts:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/accounts/{id} | Fetch a single account by id. | read | accounts:read | Current | |
Reading an account needs the accounts:read scope on the token. Acts onaccount Permission (capability) accounts:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/accounts | Create an account from at least a name and domain. | write | — | Current | |
No specific scope is documented for this write, so any valid token whose user can create accounts may call it. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook event account_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/accounts/{id} | Update an existing account. | write | — | Current | |
No specific scope is documented for this write, so any valid token whose user can edit the account may call it. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook event account_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CadencesList and read the cadences (outreach sequences) a team runs.2 | ||||||
| GET | /v2/cadences | List cadences, with filtering, paging, and sorting. | read | cadences:read | Current | |
Reading cadences needs the cadences:read scope on the token. Acts oncadence Permission (capability) cadences:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/cadences/{id} | Fetch a single cadence by id. | read | cadences:read | Current | |
Reading a cadence needs the cadences:read scope on the token. Acts oncadence Permission (capability) cadences:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Cadence membershipsList and read who is on which cadence, and add a person to a cadence.2 | ||||||
| GET | /v2/cadence_memberships | List cadence memberships, the association between a person and their time on a cadence. | read | cadences:read | Current | |
Reading memberships needs the cadences:read scope on the token. Acts oncadence_membership Permission (capability) cadences:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/cadence_memberships | Add a person to a cadence. A person_id and cadence_id are required. | write | — | Current | |
No specific scope is documented for this write. Adding someone on a teammate's behalf needs a team cadence, ownership of the cadence, or the Personal Cadence Admin permission. Acts oncadence_membership Permission (capability)None required VersionAvailable since the API’s base version Webhook event cadence_membership_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EmailsList and read sent emails and their tracking detail.2 | ||||||
| GET | /v2/activities/emails | List sent emails, with filtering, paging, and sorting. | read | emails:read | Current | |
Reading emails needs the emails:read scope. Reading the body and subject needs the privileged email_contents:read scope. Acts onemail Permission (capability) emails:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/activities/emails/{id} | Fetch a single email by id. | read | emails:read | Current | |
Reading an email needs the emails:read scope. The body and subject need the privileged email_contents:read scope. Acts onemail Permission (capability) emails:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CallsList, read, and log calls against people.2 | ||||||
| GET | /v2/activities/calls | List calls logged against people, with filtering, paging, and sorting. | read | calls:read | Current | |
Reading calls needs the calls:read scope on the token. Acts oncall Permission (capability) calls:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/activities/calls | Log a call against a person. | write | — | Current | |
No specific scope is documented for this write, so any valid token whose user can log calls may call it. Acts oncall Permission (capability)None required VersionAvailable since the API’s base version Webhook event call_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TasksList, read, create, and update the tasks a rep works through.3 | ||||||
| GET | /v2/tasks | List tasks, with filtering, paging, and sorting. | read | activities:read | Current | |
Tasks are activity records, so reading them needs the activities:read scope. Acts ontask Permission (capability) activities:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/tasks | Create a task for a user against a person or account. | write | — | Current | |
No specific scope is documented for this write, so any valid token whose user can create tasks may call it. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook event task_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/tasks/{id} | Update an existing task, including marking it complete. | write | — | Current | |
No specific scope is documented for this write. Completing a task fires the task_completed event. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook event task_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
NotesList, read, create, and update notes attached to people and accounts.3 | ||||||
| GET | /v2/notes | List notes, with filtering, paging, and sorting. | read | activities:read | Current | |
Notes are activity records, so reading them needs the activities:read scope. Acts onnote Permission (capability) activities:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/notes | Create a note on a person or account. | write | — | Current | |
No specific scope is documented for this write, so any valid token whose user can create notes may call it. Acts onnote Permission (capability)None required VersionAvailable since the API’s base version Webhook event note_createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/notes/{id} | Update an existing note. | write | — | Current | |
No specific scope is documented for this write, so any valid token whose user can edit the note may call it. Acts onnote Permission (capability)None required VersionAvailable since the API’s base version Webhook event note_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Users & teamRead the authenticated user, and list and read the team's users.3 | ||||||
| GET | /v2/me | Fetch the authenticated user the current token represents. | read | team:read | Current | |
Reading the current user is covered by the team:read scope. Acts onuser Permission (capability) team:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/users | List the users on the team, with filtering, paging, and sorting. | read | team:read | Current | |
Reading team users needs the team:read scope on the token. Acts onuser Permission (capability) team:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/users/{id} | Fetch a single user by id. | read | team:read | Current | |
Reading a user needs the team:read scope on the token. Acts onuser Permission (capability) team:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Webhook subscriptionsList and read webhook subscriptions, and create one to receive events.2 | ||||||
| GET | /v2/webhook_subscriptions | List the webhook subscriptions the application has created. | read | — | Current | |
Webhook subscriptions belong to the OAuth application that created them. Acts onwebhook_subscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/webhook_subscriptions | Create a webhook subscription for a chosen event type and callback URL. | write | — | Current | |
The required scope depends on the event type subscribed to, such as people:read for person events or cadences:read for cadence events. Acts onwebhook_subscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Salesloft can notify an app or AI agent when something happens in the workspace, like a person being created or a task being completed. It posts the object that changed to a subscribed URL, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
person_created | Fires when a person is created, and delivers the new person object. Requires the people:read scope. | /v2/people |
person_updated | Fires when a person is updated, and delivers the updated person object. Requires the people:read scope. | /v2/people/{id} |
person_deleted | Fires when a person is deleted, and delivers the deleted person object. Requires the people:read scope. | /v2/people/{id} |
account_created | Fires when an account is created, and delivers the new account object. Requires the accounts:read scope. | /v2/accounts |
account_updated | Fires when an account is updated, and delivers the updated account object. Requires the accounts:read scope. | /v2/accounts/{id} |
cadence_membership_created | Fires when a cadence membership is created, and delivers the new membership object. Requires the cadences:read scope. | /v2/cadence_memberships |
call_created | Fires when a call is created, and delivers the new call object. Requires the calls:read scope. | /v2/activities/calls |
task_created | Fires when a task is created, and delivers the new task object. Requires the tasks:read scope. | /v2/tasks |
task_updated | Fires when a task is updated, and delivers the updated task object. Requires the tasks:read scope. | /v2/tasks/{id} |
task_completed | Fires when a task is completed, and delivers the completed task object. Requires the tasks:read scope. | /v2/tasks/{id} |
note_created | Fires when a note is created, and delivers the new note object. Requires the notes:read scope. | /v2/notes |
note_updated | Fires when a note is updated, and delivers the updated note object. Requires the notes:read scope. | /v2/notes/{id} |
user_updated | Fires when a user is updated, and delivers the updated user object. Requires the team:read scope. | In-app only |
Salesloft limits how much an app or AI agent can call through a cost budget measured per minute, where each call spends from the budget and deep pages cost more.
Salesloft meters the API by cost rather than a flat request count. Each account has a budget of 600 cost per minute, which Salesloft can adjust per customer or per team. Each endpoint has a default cost of 1, and paging deep into a list adds to the cost: a page index of 101 to 150 adds 3, 151 to 250 adds 8, 251 to 500 adds 10, and 501 or beyond adds 30. Two response headers report the state, x-ratelimit-remaining-minute for what is left this minute and x-ratelimit-endpoint-cost for what the last call cost. Spending the budget returns HTTP 429.
List endpoints page through results with a page parameter, which is 1-based, and a per_page parameter that controls page size. Each response carries paging metadata describing the current page and whether more results remain. Paging beyond page 100 raises the cost of the call, so deep paging should be avoided where a filter would narrow the result instead.
Responses are JSON. The per_page page size is capped by Salesloft, and very deep page indexes are discouraged through rising cost rather than a hard ceiling.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | Authentication failed: the token is missing, invalid, or expired, or it belongs to an inactive user. A run of 401s often means an integration is calling for a user who is no longer active. | Send a valid Bearer access token, and refresh it if it has expired past its 2-hour life. |
| 403 | Forbidden | The request is authenticated but the token lacks the scope or the user lacks the permission the call needs, for example reading email bodies without the email_contents:read scope. | Grant the missing scope to the application, or use a token whose user has the required permission. |
| 404 | Not Found | The record does not exist, or it is outside what the token can see, such as a user id that does not belong to the authenticated user's team. | Confirm the id is correct and that the token's user has access to it. |
| 422 | Unprocessable Entity | The request was well-formed but a field is missing or invalid, such as creating a person without an email address or a phone and last name. | Read the returned errors, correct the named fields, and resend. |
| 429 | Too Many Requests | The per-minute cost budget was spent. The x-ratelimit-remaining-minute header reports what is left, and x-ratelimit-endpoint-cost reports what the last call cost. | Wait for the next minute, slow the request rate, and avoid paging deep into results where the cost climbs. |
| 500 | Internal Server Error | An error on Salesloft's side, in the 500 to 599 range. It is not caused by the request itself. | Retry after a short wait, and contact Salesloft support if it persists. |
Salesloft serves a single current version of its API, the second major version, alongside a legacy first version that older integrations still use.
Version 2 is the current Salesloft API, served at https://api.salesloft.com/v2 with Bearer-token authentication and cost-based rate limiting. Salesloft does not pin a dated version per account; new methods and fields are added to v2 in place rather than minting a new dated version. New integrations should build on v2.
Version 1 is the legacy Salesloft API, kept available for integrations built before v2. New work should not start on v1.
New work should build on the current version; the legacy version remains only for existing integrations.
Salesloft API reference ↗Bollard AI sits between a team's AI agents and Salesloft. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.