A contact is a person you deal with. You can link a contact to companies, opportunities and projects. This page covers reading, creating, changing and deleting contacts, and linking them to records. All endpoints sit under /api/v1/ and need an account-scoped bearer token. See Drum API authentication, permissions and rate limits.

The contact modal and contact cards in Drum, these endpoints and the MCP tools get_contact, create_contact and update_contact (Clients toolset) run the same operations, so every surface applies the same rules.

Permissions

Contacts use the company permissions of your Drum role. Each request also needs the API verb permission (for example api_create for a POST).

Action	Record permission
Read contacts	`read_companies`
Create a contact	`create_companies`
Change or restore a contact	`update_companies`
Delete a contact	`delete_companies`
Link a contact to a record, change the link or remove it	Read access to the contact (`read_companies`) plus the update permission of that record: `update_companies` for a company, or the opportunity or project update rights

A contact or record you can't read answers 404, so the API doesn't reveal that it exists.

The contact

{
  "id": 307,
  "first_name": "Sam",
  "last_name": "Taylor",
  "name": "Sam Taylor",
  "title": "Accounts manager",
  "email": "[email protected]",
  "mobile_phone": "0400 000 307",
  "office_phone": null,
  "description": null,
  "deleted": false,
  "links": [
    {"id": 9001, "record_kind": "company", "record": {"id": 301, "name": "Harbour Joinery"}, "role": null,
     "description": "Accounts", "pinned": true, "primary_financial_contact": true}
  ],
  "created_at": "2026-10-07T01:00:00Z",
  "updated_at": "2026-10-07T01:00:00Z"
}

links lists the companies, opportunities and projects of the contact that you can read, pinned first, then in the order of the contact cards. A link to a record you can't read is left out, and so is a link to a contract (contract links are managed in Drum only).

Link field	Meaning
`id`	The id of the link. MCP `delete_record` with kind `contact_link` takes this id
`record_kind`	`company`, `opportunity` or `project`
`record`	The linked record as `{id, name}`
`role`	`owner`, `primary_contractor`, `contractor` or `null`
`description`	The note on the contact card
`pinned`	Whether the contact is pinned on that record
`primary_financial_contact`	Companies only. The primary financial contact of the company

GET /api/v1/contacts

Lists the contacts you can read, sorted by last name then first name, one page at a time like the other lists. Each row has the contact fields without links.

Parameter	Meaning
`search`	Text search over the name, email and phone numbers
`company_status`	Only the contacts of companies with this company status id
`deleted`	`true` lists deleted contacts only

GET /api/v1/contacts/:id

One contact with its links. A deleted contact is shown too, with "deleted": true.

POST /api/v1/contacts

Creates a contact. The request needs api_create and create_companies. Send the fields flat or nested under contact. Only first_name is required.

Field	Meaning
`first_name`	Required. 255 characters or fewer
`last_name`, `title`, `office_phone`	Text, 255 characters or fewer
`email`, `mobile_phone`	Text, 255 characters or fewer. Each is unique in the account, deleted contacts included
`description`	Notes, 10,000 characters or fewer
`link`	Optional. One link to make at the same time: `record_kind` (`company`, `opportunity` or `project`), `record_id`, and the optional `role`, `description`, `pinned` and `primary_financial_contact` (company only). Needs the update permission of that record
`idempotency_key`	Optional. A retry with the same key and input returns the first contact with `"replayed": true`

Existing contacts are reused. When a contact that isn't deleted already has the email (any case) or, if no email matches, the mobile number, Drum returns that contact with 200 and "matched_existing": true. It doesn't change any of its fields, and it makes the link to it. A new contact returns 201 with "matched_existing": false. The contact modal in Drum works the same way.

When the match is a deleted contact, the request answers 409 contact_deleted. Restore that contact with PATCH /api/v1/contacts/:id/restore instead of creating a new one. If older records hold a deleted and an active contact with the same email in different case, the active one wins. A match you can't read answers 409 contact_exists, without showing its id or whether it's deleted.

POST /api/v1/contacts
{"first_name": "Alex", "last_name": "Nguyen", "email": "[email protected]",
 "link": {"record_kind": "project", "record_id": 104, "role": "contractor"}}

PATCH /api/v1/contacts/:id

Changes only the fields you send. null clears an optional field (last_name, title, email, mobile_phone, office_phone and description). Changing a field needs api_update and update_companies.

links (up to 20) adds links or changes the link a record already has, with the fields of link above. It merges by record: links you leave out are kept, and a link field you don't send keeps its value, so leaving out role keeps the current role. To remove a link, use DELETE on the link (below). A deleted contact answers 404 contact_not_found.

PATCH /api/v1/contacts/307
{"title": "Finance director", "links": [{"record_kind": "opportunity", "record_id": 702, "pinned": true}]}

DELETE /api/v1/contacts/:id

Deletes the contact, the same as Delete in Drum. It's a soft delete: the links stay, and you can restore the contact later. Needs api_delete and delete_companies. Answers 204.

PATCH /api/v1/contacts/:id/restore

Brings back a deleted contact. Needs api_update and update_companies. The response is the contact.

Link a contact to a company, opportunity or project

Request	Effect
`PUT /api/v1/companies/:company_id/contacts/:contact_id`	Links the contact to the company, or changes the link. `201` for a new link, `200` for a change
`PUT /api/v1/opportunities/:opportunity_id/contacts/:contact_id`	The same, for an opportunity
`PUT /api/v1/projects/:project_id/contacts/:contact_id`	The same, for a project
`DELETE /api/v1/<companies, opportunities or projects>/:id/contacts/:contact_id`	Removes the link only, the same as Un-assign in Drum. The contact stays, even when it has no other link. `204`

The body of a PUT has the optional role, description, pinned and primary_financial_contact (company only). A field you don't send keeps its value. Setting primary_financial_contact clears it on the other contacts of that company. The response is the link with contact_id. A PUT needs api_update and a DELETE needs api_delete, plus the update permission of the record.

Links to contracts are managed in Drum only. The API and MCP can't add, change or remove them.

MCP tools

The Clients toolset has get_contact, create_contact and update_contact, with the same fields and rules as the endpoints above. get_contact returns the link ids. To remove one link, use delete_record with kind contact_link and the link id. To delete a contact, use delete_record with kind contact, and bring it back with restore_record with kind contact. get_contact also returns recent_notes (the contact's 5 newest notes, each cut at 2,000 characters) and notes_count (how many notes it has). To read or write a contact's notes, see Notes API. Every agent or API token that had the Sales toolset also has Clients. See How to choose MCP toolsets for Connected Agents and API tokens.

Errors

Status	`code`	When
`422`	`missing_input`	`first_name` is missing on a create
`422`	`invalid_input`	A value doesn't parse, for example an unknown `record_kind` or `role`, `primary_financial_contact` on a record that isn't a company, more than 20 links, or the same record twice (with `field`)
`422`	`validation_failed`	The contact doesn't save (`errors` lists the messages)
`404`	`contact_not_found`	The contact is in another account, you can't read it, or (on a change) it's deleted
`404`	`company_not_found`, `opportunity_not_found`, `project_not_found`	The record of a link is deleted, in another account, or you can't read it
`404`	`contact_link_not_found`	A `DELETE` of a link that doesn't exist
`409`	`contact_deleted`	A create matched a deleted contact by email or mobile. Restore that contact instead
`409`	`contact_exists`	A create matched a contact you can't read
`403`		A missing verb permission (`{"error": "Insufficient API permissions"}`)
`403`	`not_authorized`	You don't have the contact permission, or the update permission of the record of a link

Contacts API