A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Keap API is how an app or AI agent works with a Keap account: reading and creating contacts, applying tags that drive automation, tracking sales opportunities through a pipeline, and creating orders, products, and recurring subscriptions. Access is granted through an OAuth access token, and that token carries a single broad scope named full, so it can read and write every area the connected user can reach, with no narrower per-endpoint permission to request. Keap can also push events to a subscribed receiver when a record changes, so an app learns of activity without polling.
How an app or AI agent connects to Keap determines what it can reach. The main route is the REST API, and Keap can also push events to a registered receiver, with each route governed by the access token behind it.
The newer REST surface answers under https://api.infusionsoft.com/crm/rest/v2. It is the recommended target for new work and is still gaining endpoints as Keap moves features off the older XML-RPC API.
The original REST surface answers under https://api.infusionsoft.com/crm/rest/v1. It still hosts a few areas v2 does not, including REST Hook subscription management, and shares the same OAuth token as v2.
REST Hooks deliver events to a receiver URL that has subscribed to a named event, like contact.add or contactGroup.applied. A subscription starts inactive and must be verified before Keap posts events to it.
OAuth 2.0 is the standard and required way to connect to Keap. A user authorizes the app, which receives an access token, sent as 'Authorization: Bearer
A service account key, also called a Personal Access Token, is a long-lived token tied to one Keap user and sent the same way as a Bearer token. It suits a single-account internal script rather than a marketplace integration, and carries lower rate limits than an OAuth token. Keap's older Legacy API keys are being retired in its favour.
The Keap API is split into areas an agent can act on, like contacts, tags, sales pipelines, and ecommerce orders. Each area has its own methods, and writes in the ecommerce area create real orders and charge real payments.
List, retrieve, create, update, and delete contacts, the people and records at the centre of a Keap account.
List and create tags, and apply or remove a tag from one or many contacts, which is how Keap segments people and triggers automation.
List, retrieve, create, and update company records, and read which companies carry a given tag.
List, retrieve, create, update, and delete sales opportunities, and read or change the stages of the sales pipeline.
List and create orders and products, add line items, and record payments against an order.
List, retrieve, create, and cancel recurring subscriptions tied to a contact and a subscription plan.
List campaigns, read their sequences, and add or remove contacts from a campaign sequence, plus achieve an automation goal.
Send and record emails, list and create notes, and create or update tasks against a contact.
List, create, verify, and delete REST Hook subscriptions so an app is notified when records change.
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 | |
|---|---|---|---|---|---|---|
ContactsList, retrieve, create, update, and delete contacts, the people and records at the centre of a Keap account.5 | ||||||
| GET | /v2/contacts | List contacts, with filtering and field selection. | read | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. The base path is https://api.infusionsoft.com/crm/rest. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/contacts/{contact_id} | Retrieve a single contact by id. | read | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/contacts | Create a contact. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. v1 also offers PUT /v1/contacts to create or update by a duplicate-matching rule. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contact-addRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/contacts/{contact_id} | Update a contact's fields. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contact-editRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/contacts/{contact_id} | Delete a contact. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Deletion removes the person and their history from the account. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contact-deleteRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TagsList and create tags, and apply or remove a tag from one or many contacts, which is how Keap segments people and triggers automation.4 | ||||||
| GET | /v2/tags | List tags defined in the account. | read | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/tags | Create a tag. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/tags/{tag_id}/contacts:applyTags | Apply a tag to one or more contacts. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Applying a tag is the usual way to start a Keap automation, so it can have side effects beyond labelling. The v1 equivalent is POST /v1/contacts/{contactId}/tags. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook event contactGroup-appliedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/tags/{tag_id}/contacts:removeTags | Remove a tag from one or more contacts. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. The v1 equivalent is DELETE /v1/contacts/{contactId}/tags/{tagId}. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook event contactGroup-removedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CompaniesList, retrieve, create, and update company records, and read which companies carry a given tag.3 | ||||||
| GET | /v2/companies | List companies. | read | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts oncompany Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/companies | Create a company. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts oncompany Permission (capability)None required VersionAvailable since the API’s base version Webhook event company-addRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/companies/{company_id} | Update a company. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts oncompany Permission (capability)None required VersionAvailable since the API’s base version Webhook event company-editRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Opportunities & pipelineList, retrieve, create, update, and delete sales opportunities, and read or change the stages of the sales pipeline.4 | ||||||
| GET | /v2/opportunities | List sales opportunities. | read | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts onopportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/opportunities | Create an opportunity. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts onopportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook event opportunity-addRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/opportunities/{opportunity_id} | Update an opportunity, including moving it to another pipeline stage. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts onopportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook event opportunity-editRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/opportunities/stages | List the stages of the opportunity pipeline. | read | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts onopportunity stage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Orders, products & paymentsList and create orders and products, add line items, and record payments against an order.5 | ||||||
| GET | /v2/orders | List ecommerce orders. | read | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/orders | Create an order. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Creating an order can generate an invoice and, with a payment, charge a real card. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook event order-addRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/orders/{order_id}/payments | Record or take a payment against an order. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. This can charge a real payment method. Acts onpayment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/products | List products. | read | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/products | Create a product. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook event product-addRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SubscriptionsList, retrieve, create, and cancel recurring subscriptions tied to a contact and a subscription plan.3 | ||||||
| GET | /v2/subscriptions | List recurring subscriptions. | read | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/subscriptions | Create a recurring subscription for a contact. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. This starts recurring billing. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscription-addRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/subscriptions/{subscription_id}:deactivate | Cancel an active subscription. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. This stops future recurring charges. Acts onsubscription Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscription-editRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Campaigns & automationList campaigns, read their sequences, and add or remove contacts from a campaign sequence, plus achieve an automation goal.3 | ||||||
| GET | /v2/campaigns | List campaigns. | read | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/campaigns/{campaign_id}/sequences/{sequence_id}:addContacts | Add one or more contacts to a campaign sequence. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Adding a contact to a sequence can immediately begin automated emails and other steps. The v1 equivalent is POST /v1/campaigns/{campaignId}/sequences/{sequenceId}/contacts. Acts oncampaign sequence Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/campaigns/{campaign_id}/sequences/{sequence_id}:removeContacts | Remove one or more contacts from a campaign sequence. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts oncampaign sequence Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Emails, notes & tasksSend and record emails, list and create notes, and create or update tasks against a contact.4 | ||||||
| POST | /v2/emails:send | Send an email to a contact and record it. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. This delivers a real message to a real recipient. The v1 equivalent is POST /v1/emails/queue. Acts onemail Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/emails | List recorded emails. | read | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts onemail Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/contacts/{contact_id}/notes | Create a note on a contact. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts onnote Permission (capability)None required VersionAvailable since the API’s base version Webhook event note-addRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/tasks | Create a task. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook event task-addRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
REST HooksList, create, verify, and delete REST Hook subscriptions so an app is notified when records change.2 | ||||||
| GET | /v1/hooks | List the REST Hook subscriptions stored for the application. | read | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. REST Hook management lives on the v1 surface. Acts onhook subscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/hooks | Create a REST Hook subscription for a chosen event, then verify it. | write | — | Current | |
Keap OAuth grants a single 'full' scope, so there is no narrower per-endpoint permission. A new subscription starts inactive and must be confirmed at POST /v1/hooks/{key}/verify before events flow. Acts onhook subscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Keap can notify an app or AI agent when something changes in an account, like a contact being added or a tag being applied, instead of the app repeatedly asking. Keap calls these REST Hooks: a receiver subscribes to a named event, and Keap posts a payload listing the changed records when that event fires.
| Event | What it signals | Triggered by |
|---|---|---|
contact.add | Fires when a contact is created in the account. | /v2/contacts |
contact.edit | Fires when a contact's details are changed. | /v2/contacts/{contact_id} |
contact.delete | Fires when a contact is deleted. | /v2/contacts/{contact_id} |
contactGroup.applied | Fires when a tag is applied to a contact. | /v2/tags/{tag_id}/contacts:applyTags |
contactGroup.removed | Fires when a tag is removed from a contact. | /v2/tags/{tag_id}/contacts:removeTags |
company.add | Fires when a company record is created. | /v2/companies |
company.edit | Fires when a company record is changed. | /v2/companies/{company_id} |
opportunity.add | Fires when an opportunity is created. | /v2/opportunities |
opportunity.edit | Fires when an opportunity is changed, including a stage move. | /v2/opportunities/{opportunity_id} |
order.add | Fires when an order is created. | /v2/orders |
product.add | Fires when a product is created. | /v2/products |
subscription.add | Fires when a recurring subscription is created. | /v2/subscriptions |
subscription.edit | Fires when a subscription is changed, including being cancelled. | /v2/subscriptions/{subscription_id}:deactivate |
note.add | Fires when a note is created. | /v2/contacts/{contact_id}/notes |
task.add | Fires when a task is created. | /v2/tasks |
Keap limits how fast and how much an app or AI agent can call, through a per-minute query rate and a daily query quota that depend on the kind of token, plus a per-second spike ceiling on bursts.
Keap limits how fast and how much an app can call, with limits that depend on the kind of token. An OAuth access token gets 1,500 queries per minute and 150,000 queries per day, where the daily quota resets at midnight UTC. A service account key, also called a Personal Access Token, gets 10 queries per second, 240 queries per minute, and 30,000 queries per day. On top of the per-minute rate, a spike-protection policy caps short bursts at about 25 calls per second by default. Every response carries x-keap-tenant-throttle-available and x-keap-product-quota-available headers reporting how much of the throttle and quota remain, and going over returns HTTP 429.
List endpoints page through results. The v1 surface uses offset paging through limit and offset parameters, while the v2 surface uses cursor paging, returning a next page token to pass back on the following request. Page sizes are capped per endpoint.
Requests and responses are JSON. A single REST Hook delivery lists at most 1,000 changed records, and larger result sets are split across pages rather than returned at once.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed or a field failed validation. | Correct the request body or parameters named in the response and resend. |
| 401 | Unauthorized | The access token is missing, invalid, or expired. | Refresh the access token with the refresh token, then retry with a valid Bearer token. |
| 403 | Forbidden | The token is valid but the account or user is not permitted to perform the action. | Confirm the connected user has the right access in Keap for this action. |
| 404 | Not Found | The requested record or path does not exist. | Check the id and the path, then retry. |
| 409 | Conflict | The request conflicts with the current state of the record, such as a duplicate. | Refetch the current state, resolve the conflict, then retry. |
| 429 | Too Many Requests | A rate limit was exceeded, either the per-minute query rate, the daily quota, or the per-second spike ceiling. | Slow down using the x-keap-tenant-throttle-available and x-keap-product-quota-available headers, then retry after a pause. |
| 500 | Internal Server Error | An unexpected error occurred on Keap's side. | Retry after a short delay, and contact Keap support if it persists. |
Keap runs two REST API generations side by side. The older v1 surface and the newer, still-growing v2 surface coexist, while the original XML-RPC API is being retired.
REST API v2 is the newer REST surface, answering under the /rest/v2 path and sharing the same OAuth token as v1. Keap has been adding endpoints to it to reach feature parity with the legacy XML-RPC API ahead of that API's retirement, reporting parity reached around October 2025. It is the recommended target for new integrations.
REST API v1 is the original RESTful API, answering under the /rest/v1 path. It uses OAuth 2.0, offers roughly half the call volume of the equivalent XML-RPC work, and still hosts a few areas v2 does not, including REST Hook subscription management.
Keap announced the retirement of its older Legacy API keys, directing developers to OAuth 2.0 or a service account key (Personal Access Token) instead. This was the start of a broader move toward OAuth-only access.
Keap scheduled the final retirement of its legacy XML-RPC API for the end of 2026, with brownouts through the year to help integrations find remaining dependencies. REST v2 is the migration target, brought to feature parity with XML-RPC so integrations can move before the sunset.
An integration can call v1 and v2 endpoints from the same access token, and should prefer v2 for new work.
Keap developer announcements ↗Bollard AI sits between a team's AI agents and Keap. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.