Carom API

The Carom API reads and updates the records Carom keeps for your team: contacts, organizations, deals, threads, files, tasks, and the rest. API keys can call every operation in this reference. A few operations are available only in the Carom app; Authentication lists them.

Every request is made over HTTPS to https://api.carom.io and authenticated with an API key that acts as the user who created it. The OpenAPI 3.1 specification describes the same operations in machine-readable form.

#Make a first request

Create an API key in the Carom app under Settings › API keys. Carom shows the key once, when you create it. Keep it somewhere safe, such as an environment variable:

export CAROM_API_KEY=carom_sk_…

Then send it as a bearer token. Retrieve your key’s user is a good first call: it needs only a read key, and its response shows which user the key acts as.

A 401 unauthorized means the key is missing, mistyped, revoked, or expired. A 403 api_access_disabled means an admin has turned API access off for your account. Authentication covers keys in full.

Next steps

Read Authentication to choose a key tier, then Errors and Pagination. A good second call is List contacts.

get/users/current

curl https://api.carom.io/users/current \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "user": {
    "id": "9c41d2e8-3f6a-4b7c-8d1e-5a2f7b9c0d3e",
    "first_name": "Dana",
    "last_name": "Whitfield",
    "email_address": "dana@harborline.example",
    "is_admin": true,
    "is_owner": false,
    "status": "active",
    …
  }
}

#Conventions

JSON in, JSON out

Request and response bodies are JSON. Send Content-Type: application/json with any request that has a body; any other content type gets 415 unsupported_media_type. An Accept header, if you send one, must allow application/json, or the request gets 406 not_acceptable. Most bodies wrap the attributes in a key named after the resource, such as {"contact": {…}}, and single-record responses are wrapped the same way.

Identifiers

Every id is a UUID string. References to other records use the same ids, in attributes named after the record, such as contact_id or pipeline_id. An id in the path that isn’t a valid UUID returns 404 record_not_found, the same as an id that doesn’t exist. The path names the record an operation acts on; a body key with the same name as a path parameter must match it or be left out.

Dates and times

Dates are ISO 8601 calendar dates, such as 2026-09-04. Timestamps are ISO 8601 date-times in UTC, such as 2026-09-04T21:17:09.332Z. Send dates and timestamps in ISO 8601 as well.

Empty values

Unless an attribute is marked as appearing only in some responses, it is always present, and null when it has no value.

Lists

List endpoints return a collection object with the page of records and the information you need to fetch the next page. Some lists page with an opaque cursor, others by page number, and a few return every record in one response. Pagination explains each.

Key tiers

Each operation is marked Read key or Write key. A read key can call operations marked Read key. A read/write key can call both. See Read and write keys. An account admin can limit every key in the account to reading, or turn API access off; see Account API access.

Status codes

A successful request answers 200, or 201 when it creates a record. Most deletes answer 204 with no body. An operation that starts work Carom finishes later, such as generating a briefing, answers 202. HTTP statuses lists every status.

Rate limit

Each API key can make 600 requests a minute. Over the limit, requests get 429 rate_limited; wait the number of seconds in the Retry-After header, then try again. See Rate limits.

Test mode

There is no test mode: every request reads and changes your account’s real data, so use a read key while you build.

Versions

The API has a single version; there is no version parameter or header.

Errors

A failed request returns a 4xx or 5xx status and an error object with a stable code and a readable message. Branch on the code. Errors lists the codes any request can return; each operation lists its own.

#Resources

Each page documents one resource: its object, its operations, and the errors they return.