API resources and endpoints

The API works with five kinds of record: contacts, matters, leads, practice areas, and matter types. Each supports list, create, read, update, and delete.

This page covers what every endpoint has in common, and links to the reference page for each resource.

Before using these endpoints, make sure you can authenticate. See Authentication and scopes. All paths below sit under the base address https://api.esqase.com.

The resources

Each resource has its own reference page with every field, limit, example, and error:

• Contacts endpoints: the people and companies your firm works with.
• Matters endpoints: your cases and engagements, with their clients and team.
• Leads endpoints: prospective clients in your intake pipeline.
• Practice areas endpoints: the areas of law your matters sit under, and the stages they move through.
• Matter types endpoints: the sub-types defined within a practice area.
• Custom fields in the API: your firm's own fields on contacts, matters, and leads.

How the endpoints are shaped

Each resource follows the same pattern, where {id} is the id of one record:

Replace <resource> with contacts, matters, leads, practice-areas, or matter-types.

Two rules hold everywhere:

• Creates return 201. Reads, updates, and deletes return 200.
• Deletes are soft deletes. A deleted record is archived out of the active lists rather than erased, exactly as deleting it in the dashboard is. The response is { "data": { "id": "...", "deleted": true } }.

What comes back

Every successful response wraps its payload in a data property. A single record is an object; a list is an array plus a pagination block. Errors replace data with an error object holding a code and a message. See Authentication and scopes for the full error reference.

Updates are partial: send only the fields you want to change, and everything you leave out keeps its current value. Two places behave differently and each page says so, a contact's emails and phones lists replace rather than merge, and custom fields merge key by key.

Paging through lists

Every list endpoint returns records in pages so you never pull your whole firm in one call. Control the page with two query parameters:

• limit: how many records to return. Minimum 1, maximum 100, default 20.
• offset: how many records to skip before the page starts. Minimum 0, default 0.

For example, GET /v1/contacts?limit=50&offset=0 returns the first 50 contacts, and ?limit=50&offset=50 returns the next 50.

curl "https://api.esqase.com/v1/contacts?limit=2&offset=0" \
  -H "Authorization: Bearer $ESQASE_API_KEY"

Every list wraps its records in a data array and adds a pagination object with the limit, offset, and total:

{
  "data": [
    { "id": "a1b2c3d4-0001-4a1b-9c2d-1234567890ab", "name": "Jane Doe" },
    { "id": "a1b2c3d4-0002-4a1b-9c2d-1234567890ab", "name": "Acme Holdings" }
  ],
  "pagination": {
    "limit": 2,
    "offset": 0,
    "total": 128
  }
}

When offset plus limit reaches total, you have read every record. The list endpoints take no filters or sorting today, so page through and filter on your side. List order is not specified, so if records are being created or deleted while you page, a record can appear twice or be missed. For a one-off export, page quickly and de-duplicate on id.

GET /v1/matter-types is the one list that needs more than paging: it also requires a practiceAreaId query parameter, because matter types always belong to one practice area.

Where the ids come from

Most integrations need to resolve a few ids before their first write:

• Contact ids come from GET /v1/contacts or from the response when you create one.
• Practice area ids and stage ids come from GET /v1/practice-areas, then GET /v1/practice-areas/{id} for the stages. The list endpoint leaves stages out.
• Lead stage ids come from a lead you already have. Leave leadStageColumnId out and the lead lands in your firm's first stage.
• Member ids come from your firm's members in the dashboard. The API has no members endpoint.
• Custom field names and ids come from GET /v1/custom-fields.

What happens to a record after the API touches it

Records created or changed through the API are not stored off to the side; they join your firm's data like any other:

• They appear everywhere the matching record appears in the dashboard (lists, detail pages, kanban boards, and reports).
• Every write is recorded in your firm's audit log, attributed to the member who created the key and noting which key did it. You can see API activity right alongside changes made by hand.
• Contacts and matters become searchable as soon as they are created, the same as records you add in the app.

Common questions

• How do I get the id of a record? From the list endpoint (GET /v1/<resource>) or from the response when you create one.
• Do deletes erase data? No. Deletes through the API are soft deletes, the same as deleting in the app. Records are archived, not destroyed.
• Can I search or filter a list? Not yet. The list endpoints accept limit and offset only (plus the required practiceAreaId on matter types).
• Which resources have custom fields? Contacts, matters, and leads. See Custom fields in the API.
• Is there a machine-readable version of all this? Yes. The API publishes an OpenAPI 3.1 description at GET /v1/openapi.json, which needs no key. See Authentication and scopes.

Related

• The Esqase API
• Managing API keys
• Authentication and scopes
• Contacts endpoints
• Matters endpoints
• Custom fields in the API