Records

Record calls use the catalog key exactly. Company is valid. company and PortCo are 400 unknown_entity.

Method	Path	What it does
GET	/api/v1/x/records/{entityType}	A page of records
GET	/api/v1/x/records/{entityType}/{id}	One record
POST	/api/v1/x/records/{entityType}	Create
PATCH	/api/v1/x/records/{entityType}/{id}	Change the keys you send
POST	/api/v1/x/records/{entityType}/{id}/relations	Relate Company and Person

Company, Person, Deal, Lead, and Investor are the types this API reads and writes. Any other catalog type returns 400 invalid_parameter. Permissions are on the catalog.

A list item is { id, fields }. One record is { id, entityType, fields, relations, version }. fields includes every catalog field for that type. An empty value is null. Custom values use their stored keys. version starts at 1 and increases on each write.

List

Query parameters are cursor, limit, q, sort, filter, and starting_after.

cursor is a page number. Omit it for the first page. nextCursor is the next page, or absent on the last page. limit defaults to 25 and must be from 1 to 100. A value outside that range is rejected. It is not clamped.

Page order follows the grid: company and person by name, lead by the time it was sourced. A record created, deleted, or renamed while you page can appear twice or disappear. Read nextCursor from each response and stop when it is absent.

starting_after reads the same list in the order the records were created, then by id. A new record lands at the end. Changing a record does not move it. Send starting_after=start for the first page. When another page exists, nextStartingAfter is the id of the last row. Pass that id as starting_after on the next call, and stop when nextStartingAfter is null. In that mode nextCursor is null. On a page-number request, nextStartingAfter is null.

q and filter apply to both modes. Sending cursor or sort together with starting_after is 400 invalid_parameter. An id that is not in this filtered list is 404 not_found.

q searches the name the list already searches. sort is a filterable field key, with a leading - for descending. filter is the list filter the product already uses: groupLogic, groups, and conditions of field, operator, and value. The field must be marked filterable. An unknown or non-filterable field is 400, and the list does not run.

Create and patch

The body is a map of catalog field keys. expectedCatalogVersion and acknowledgeDuplicates are control fields, not record fields.

Absent keys on a patch stay as they are. null clears a field the catalog marks clearable. A missing required field, a wrong JSON type, a choice outside options, or a key that is not on that type is 400.

Without If-Match, two patches of the same record both succeed, and the later write wins. Send If-Match with the version from the last read (3 or "3") when the patch must fail if someone else wrote first. A mismatch is 412 version_conflict and nothing is written. Read the record again and decide whether your patch is still the one you want. Then send that patch with the new version. Putting the new version on the old body can overwrite the edit you just read. A header that is not a positive integer is 400 invalid_parameter. expectedCatalogVersion fails the call only when the catalog changed.

A company or person that matches an existing record is 409 possible_duplicates. matches lists each id, name, and score. Send acknowledgeDuplicates: true to create it anyway.

These keys are required even when they are easy to miss, because the catalog is the list to trust:

Type	Required on create
Company	name, companyType
Person	firstName, lastName
Deal	companyId, strategyId
Lead	companyName
Investor	primaryOrganisationId, investorType

Deal stage, companyId, and strategyId are set on create. A later patch cannot change them. Lead sourceType and sourceId are create-only. Lead status and companyId are read-only.

{
  "name": "Northwind Health",
  "companyType": "PrivateCompany"
}

POST /api/v1/x/records/Company with that body creates the company in the firm on the token.

Relate

{
  "relation": "people",
  "toEntityType": "Person",
  "toId": "00000000-0000-0000-0000-000000000000"
}

people on a company, and companies on a person, are the only writable relations. Both create a current company role of type Key employee. The body does not take a role title. Any other pair is 400.

Delete, merge, and deduplication are not on this API.