A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Close API is how an app or AI agent works with a Close CRM organization: creating and updating leads and their contacts, tracking opportunities through a pipeline, logging activities like calls, emails, and notes, and managing tasks. Access is granted through an API key or an OAuth token, and on Close that credential carries full account access rather than narrow per-method permissions, so a key reaches everything the user behind it can. A change writes to an Event Log that Close can push to a subscribed endpoint as it happens.
How an app or AI agent connects to Close determines what it can reach. There is a route for making calls and a route for receiving events, and each is governed by the credential behind it, which on Close is a key or token that carries full account access rather than narrow per-method permissions.
The REST API takes JSON request bodies, returns JSON, and pages through lists at https://api.close.com/api/v1. A call authenticates with an API key over HTTP Basic auth, or with an OAuth bearer token. There is one stable v1 version.
Close POSTs events from the Event Log to a subscribed HTTPS URL as activity happens. A subscription is created over the API for a chosen set of object types and actions, and its response returns a signature_key. Each delivery carries close-sig-hash and close-sig-timestamp headers, where the hash is a sha256 HMAC of the timestamp and payload, so the receiver can confirm the request came from Close.
An API key is sent over HTTP Basic auth, as the username, with a blank password. It is scoped to one user and organization, and carries that user's full access to the account; Close does not attach per-resource scopes to a key. Keys are created and deleted in Settings, and suit scripts and internal, server-side integrations.
OAuth 2.0 uses the authorization-code flow at app.close.com/oauth2/authorize, exchanging the code at api.close.com/oauth2/token for a bearer access token. The grant currently carries the all.full_access offline_access scope, so the token has the same full account access as an API key, and offline_access returns a refresh token because the access token expires after one hour. It suits user-facing integrations where a user connects their own Close account.
The Close API is split into areas an agent can act on, like leads, contacts, opportunities, the activities logged against them, and tasks. Each area has its own methods, and a write can change real CRM records that a sales team relies on.
List and filter leads, create, read, update, delete, and merge them. A lead is the central object that holds contacts, opportunities, activities, and tasks.
List, create, read, update, and delete contacts. Each contact belongs to one lead and holds phone numbers, email addresses, and URLs.
List and filter, create, read, update, and delete opportunities, the potential deals tracked against a lead with a status and value.
List, create, read, update, and delete the activities logged against a lead, including notes, calls, and emails.
List and filter, create, read, update, bulk-update, and delete the tasks assigned to users.
List, create, read, update, and delete the custom field definitions that extend leads, contacts, opportunities, and activities.
Read the current user, list and read users in the organization, and read or update the organization's details.
List, create, read, update, and delete webhook subscriptions, and read the Event Log that those subscriptions stream from.
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 | |
|---|---|---|---|---|---|---|
LeadsList and filter leads, create, read, update, delete, and merge them. A lead is the central object that holds contacts, opportunities, activities, and tasks.6 | ||||||
| GET | /api/v1/lead/ | List or search leads, filtered with query parameters or the Advanced Filtering API. | read | — | Current | |
Read-only. An API key has full access; an OAuth token carries the all.full_access scope, so no narrower permission applies. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/lead/ | Create a new lead, optionally with nested contacts in the same request. | write | — | Current | |
A core write. An API key and an OAuth token both carry full account access, so there is no narrower permission to scope this to. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook event lead.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/lead/{id}/ | Get a single lead by ID, with its contacts and recent activity. | read | — | Current | |
Read-only. Use the _fields parameter to choose which fields are returned. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/lead/{id}/ | Update an existing lead's fields. | write | — | Current | |
A core write. No narrower permission applies under either credential. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook event lead.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/lead/{id}/ | Delete a lead. | write | — | Current | |
Deleting a lead also deletes its child activities, opportunities, tasks, and contacts, each firing its own deleted event. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook event lead.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/lead/merge/ | Merge two leads, combining the source lead into the destination lead. | write | — | Current | |
A merge also produces updated and deleted events on the leads and related objects involved. Acts onlead Permission (capability)None required VersionAvailable since the API’s base version Webhook event lead.mergedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ContactsList, create, read, update, and delete contacts. Each contact belongs to one lead and holds phone numbers, email addresses, and URLs.5 | ||||||
| GET | /api/v1/contact/ | List contacts. | read | — | Current | |
Read-only. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/contact/ | Create a new contact on a lead. | write | — | Current | |
A core write. Each contact belongs to exactly one lead. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contact.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/contact/{id}/ | Fetch a single contact by ID. | read | — | Current | |
Read-only. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/contact/{id}/ | Update an existing contact. | write | — | Current | |
A core write. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contact.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/contact/{id}/ | Delete a contact. | write | — | Current | |
Irreversible. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contact.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OpportunitiesList and filter, create, read, update, and delete opportunities, the potential deals tracked against a lead with a status and value.5 | ||||||
| GET | /api/v1/opportunity/ | List or filter opportunities. | read | — | Current | |
Read-only. Acts onopportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/opportunity/ | Create an opportunity against a lead. | write | — | Current | |
A core write. An opportunity carries a status, a value, and a confidence. Acts onopportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook event opportunity.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/opportunity/{id}/ | Retrieve a single opportunity by ID. | read | — | Current | |
Read-only. Acts onopportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/opportunity/{id}/ | Update an opportunity, including moving it to a new status. | write | — | Current | |
Changing status_id moves the deal through the pipeline. A separate opportunity.status_change activity also records the move. Acts onopportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook event opportunity.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/opportunity/{id}/ | Delete an opportunity. | write | — | Current | |
Irreversible. Acts onopportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook event opportunity.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ActivitiesList, create, read, update, and delete the activities logged against a lead, including notes, calls, and emails.4 | ||||||
| GET | /api/v1/activity/ | List or filter all activity types logged against leads and contacts. | read | — | Current | |
Read-only. Each activity type also has its own type-specific endpoint. Acts onactivity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/activity/note/ | Create a note activity on a lead. | write | — | Current | |
A core write that logs a note against the lead. Acts onnote activity Permission (capability)None required VersionAvailable since the API’s base version Webhook event activity.note.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/activity/call/ | Log an external call activity on a lead. | write | — | Current | |
Records a call made outside Close against the lead's timeline. Acts oncall activity Permission (capability)None required VersionAvailable since the API’s base version Webhook event activity.call.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/activity/email/ | Create an email activity, as a draft, an outbox send, or a logged message. | write | — | Current | |
Setting status to outbox sends the email through Close, which then fires an activity.email.sent event. Acts onemail activity Permission (capability)None required VersionAvailable since the API’s base version Webhook event activity.email.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TasksList and filter, create, read, update, bulk-update, and delete the tasks assigned to users.5 | ||||||
| GET | /api/v1/task/ | List or filter tasks. | read | — | Current | |
Read-only. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/task/ | Create a task on a lead. | write | — | Current | |
A core write. A task is assigned to a user with a due date. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook event task.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/task/ | Bulk-update tasks matching a filter, for example to mark many complete. | write | — | Current | |
Applies the same change across every matching task in one call. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook event task.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/task/{id}/ | Update a single task, including marking it complete. | write | — | Current | |
Setting is_complete to true fires a task.completed event in addition to task.updated. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook event task.completedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/task/{id}/ | Delete a task. | write | — | Current | |
Irreversible. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook event task.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Custom fieldsList, create, read, update, and delete the custom field definitions that extend leads, contacts, opportunities, and activities.2 | ||||||
| GET | /api/v1/custom_field/lead/ | List the custom field definitions for leads. | read | — | Current | |
Read-only. Separate endpoints cover contact, opportunity, and activity custom fields. Acts oncustom field Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/custom_field/lead/ | Create a new custom field definition for leads. | write | — | Current | |
A schema write that adds a field to every lead in the organization. Acts oncustom field Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Users & organizationRead the current user, list and read users in the organization, and read or update the organization's details.3 | ||||||
| GET | /api/v1/me/ | Fetch information about the authenticated user. | read | — | Current | |
Read-only. Returns the user the key or token belongs to. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/user/ | List the users in the organization. | read | — | Current | |
Read-only. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/organization/{id}/ | Update an organization's details. | write | — | Current | |
An organization-level write that changes settings affecting all members. Acts onorganization Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Webhooks & eventsList, create, read, update, and delete webhook subscriptions, and read the Event Log that those subscriptions stream from.4 | ||||||
| GET | /api/v1/webhook/ | List the webhook subscriptions for the organization. | read | — | Current | |
Read-only. Acts onwebhook subscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/webhook/ | Create a webhook subscription for a chosen set of object types and actions. | write | — | Current | |
The response returns a signature_key used to sign deliveries. Up to 40 subscriptions per organization. Acts onwebhook subscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/webhook/{id}/ | Delete a webhook subscription. | write | — | Current | |
Stops Close from POSTing events to that URL. Acts onwebhook subscription Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/event/ | Retrieve a list of events from the Event Log. | read | — | Current | |
Read-only. The Event Log retains events for 30 days and uses cursor-based pagination. Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Close can notify an app when something happens in an organization, like a lead being created or an opportunity changing status. It POSTs the event from the Event Log to a subscribed URL, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
lead.created | A lead is created in the organization, regardless of how. | /api/v1/lead/ |
lead.updated | A lead's basic fields change, or a contact, address, or custom field value is added, removed, or updated. | /api/v1/lead/{id}/ |
lead.deleted | A lead is deleted, which also fires deleted events on its child activities, opportunities, tasks, and contacts. | /api/v1/lead/{id}/ |
lead.merged | Two leads are merged, with the data of the resulting destination lead in the payload. | /api/v1/lead/merge/ |
contact.created | A contact is created in the organization. | /api/v1/contact/ |
contact.updated | A contact's basic or nested fields change, like a name, an email, a phone number, or a URL. | /api/v1/contact/{id}/ |
contact.deleted | A contact is deleted. | /api/v1/contact/{id}/ |
opportunity.created | An opportunity is created. | /api/v1/opportunity/ |
opportunity.updated | An opportunity's basic fields change, like status, date_won, value, value_period, or confidence. | /api/v1/opportunity/{id}/ |
opportunity.deleted | An opportunity is deleted. | /api/v1/opportunity/{id}/ |
activity.note.created | A note activity is created on a lead. | /api/v1/activity/note/ |
activity.call.created | A call activity is created, whether from a Close call, an inbound call, or a manually logged one. | /api/v1/activity/call/ |
activity.email.created | An email activity is created, either a synced incoming email or an outgoing draft or outbox email. | /api/v1/activity/email/ |
activity.email.sent | An outgoing email is actually sent through Close, not when it is queued in the outbox. | /api/v1/activity/email/ |
task.created | A task is created. | /api/v1/task/ |
task.updated | A task's basic fields change, like is_complete, date, text, or subject. | /api/v1/task//api/v1/task/{id}/ |
task.completed | A task is marked as done. | /api/v1/task/{id}/ |
task.deleted | A task is deleted. | /api/v1/task/{id}/ |
Close limits how fast an app can call, by a request rate measured per second and applied separately to each endpoint group, with a per-key ceiling sitting under a higher per-organization one.
Close meters requests by rate, per second, and per endpoint group, where a group combines a set of URL paths and HTTP methods so light reads can be allowed more often than heavy writes. Two ceilings apply: a per-API-key limit, and a per-organization limit that is currently three times the per-key limit, so if a key is allowed 20 requests per second the organization is allowed 60 across all of its keys. Going over returns HTTP 429, and the RateLimit response header reports limit, remaining, and reset (in seconds). On a 429, Close recommends pausing for the rate_reset value before retrying, which is more accurate than the retry-after header it also sends.
Most list endpoints use offset pagination with _skip and _limit, fetching successive pages by raising _skip, and a has_more field signals whether the last page was reached. Offset paging has a maximum _skip that varies per resource, so for large result sets Close recommends narrowing by date range or using the Export API. The Advanced Filtering API and the Event Log use cursor-based pagination instead, which avoids issues with data changing between requests.
A list endpoint caps _limit at a maximum that varies per resource. The Event Log retains events for 30 days. An organization can hold up to 40 webhook subscriptions, raised to a higher ceiling for approved automation platforms.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | There was an issue with the request, like a malformed body or an invalid parameter. | Read the error in the response body, fix the request, and resend. |
| 401 | Unauthorized | The request needs to be authenticated, or the credential is missing or invalid. | Send a valid API key over HTTP Basic auth, or a valid OAuth bearer token, and refresh an expired token. |
| 402 | Payment Required | The request could not be completed because a limit of the current Close plan was reached. | Upgrade the plan or reduce usage to stay within the plan's limit. |
| 403 | Forbidden | The operation was not allowed for this user or organization. | Confirm the user has permission for the action in Close, then retry. |
| 404 | Not Found | The URL was not found, or the object does not exist or is not visible to this credential. | Verify the path and the object ID. |
| 405 | Method Not Allowed | The HTTP method is not supported for this endpoint. | Use a method the endpoint supports, like GET to read or POST to create. |
| 415 | Unsupported Media Type | The request used a format Close does not support. | Send a JSON body with the Content-Type set to application/json. |
| 429 | Too Many Requests | A rate limit was exceeded for the endpoint group, at the per-key or per-organization level. | Pause for the number of seconds in the rate_reset value, then retry. The RateLimit header reports limit, remaining, and reset. |
Close runs a single stable version of its API, with backward-compatible changes shipped continuously rather than through dated version numbers.
Close runs a single stable version of its API under the v1 path. Changes are backward-compatible and shipped continuously rather than as dated versions, so there is no version header to pin and no older parallel version to migrate from. New capabilities are announced on the API changelog, while changes to the product itself appear on the separate product updates page.
There is one current version to build against.
Close API changelog ↗Bollard AI sits between a team's AI agents and Close. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.