REST API reference

Authentication

An admin creates API keys in Setup → API & Webhooks. Each key belongs to one workspace and is either read only or read & write, for all objects or only the ones chosen. The key is shown once when it's created; we keep only a fingerprint (SHA-256), so a lost key can't be shown again — revoke it and create a new one. Revoking takes effect straight away. Setup shows when each key was last used.

Authorization: Bearer xpi_…

Changes made through the API show in each record's history as “via API · key name”, and start playbook rules exactly like changes in the app.

Endpoints

curl "https://xpicrm.com/api/v1/clients?limit=2&health=At%20Risk" \
  -H "Authorization: Bearer $XPI_KEY"

{
  "data": [
    {
      "id": "0b7c…",
      "clientNumber": "C-00012",
      "name": "Globex Inc.",
      "health": "At Risk",
      "arr": 48000,
      "renewalDate": "2026-12-15",
      "owner": { "id": "5f1e…", "name": "Alex Morgan" },
      "daysToRenewal": 68,
      "openBalance": 1200,
      "documents": [{ "id": "f19a…", "name": "contract.pdf", "size": 182044 }],
      "createdAt": "2026-03-02T09:14:00Z",
      "updatedAt": "2026-10-07T10:12:00Z"
    }
  ],
  "total": 1, "limit": 2, "offset": 0
}

curl -X POST "https://xpicrm.com/api/v1/clients?match=name" \
  -H "Authorization: Bearer $XPI_KEY" -H "Content-Type: application/json" \
  -d '[{ "name": "Acme Corp", "website": "https://acme.example" },
       { "name": "New Co", "tier": "Gold", "owner": "alex@example.com" }]'

{ "created": 1, "updated": 1, "errors": [], "ids": ["2c4e…", "9a1d…"] }

curl "https://xpicrm.com/api/v1/clients/2c4e…" -H "Authorization: Bearer $XPI_KEY"

{ "data": { "id": "2c4e…", "name": "Acme Corp", "…": "…" } }

curl -X PATCH "https://xpicrm.com/api/v1/clients/2c4e…" \
  -H "Authorization: Bearer $XPI_KEY" -H "Content-Type: application/json" \
  -d '{ "health": "At Risk" }'

{ "data": { "id": "2c4e…", "health": "At Risk", "…": "…" } }

curl -X DELETE "https://xpicrm.com/api/v1/clients/2c4e…" -H "Authorization: Bearer $XPI_KEY"

{ "deleted": "2c4e…" }

Filters and paging

Lists are ordered by creation time. Use limit (up to 1,000, default 100) and offset to page; total is the number of matching records. updated_since returns only records changed after that moment, so you can sync changes. Any other parameter is an exact, case-insensitive match on that field key; for links, pass the linked record's id.

Creating and updating (upserts)

POST accepts one record, an array, or { "records": [...] } (up to 1,000). A record with an id updates that record. Otherwise ?match=field1,field2 finds an existing record with the same values (default: the object's unique fields, otherwise its name) and updates it; if none is found, a new record is created. Updates change only the fields you send; everything else stays as it is. A failed record never stops the others: the response is 207 with an errors list (by position in your request).

Payload format

• Fields use their keys (below). id, createdAt and updatedAt are always included and can't be set.
• Links come back as { id, name }. If the key can't access the linked object, only { id }. Send a link as its id, its name, or { id }.
• People come back as { id, name }. Send an id, an email address or a full name.
• Files come back as [{ id, name, size }] and can't be set through the API.
• Calculated values (formulas, roll-ups, fields from linked records) are included and are read only. The health score is read only too.

Errors

Errors look like { "error": { "status": 422, "message": "…" } }.

• 401: Missing, wrong or revoked API key
• 403: The key has no access to this object, or it is read-only and the request writes
• 404: Unknown object or record
• 405: Method not allowed on this path
• 422: Validation failed

Objects and fields

The default objects are listed here. Your workspace may have more objects and fields; their keys are shown in Setup → Object Manager.

See also the CSV import guide.