Contacts

A contact is one record from one source: an email address from your sequencer, a LinkedIn profile from HeyReach, a record synced in from Close CRM. RevyOps creates or updates a contact record each time a webhook event is received from a connected platform, or when you create one through the API. For how contacts are searched, filtered, and viewed in the RevyOps UI, see the Contacts user guide.

Configuration


API path	`/public/v2/contacts` (recommended) or `/public/contacts` (v1)
Singular	contact
Plural	contacts

v2 endpoints add LinkedIn engagement fields and do_not_contact, and return contact_custom_fields as a read-only summary string with a separate contact_custom_fields_input field for writes. v1 remains supported for existing integrations. See Versioning.

Attributes

Attribute	API field	Type	Writable?	Notes
ID	`id`	integer	Read-only
Last updated	`updated_time`	string (date-time)	Read-only
Email	`email`	string, nullable	Writable	Unique per workspace. A contact needs at least one of email, LinkedIn URL, or phone to be created.
LinkedIn URL	`linkedin_url`	string, nullable	Writable
Phone	`phone`	string, nullable	Writable
First name	`first_name`	string	Writable
Last name	`last_name`	string	Writable
Job title	`job_title`	string, nullable	Writable
Company	`company_id`	integer, nullable	Writable	Relationship to a Company. Accepts an integer company ID or a domain string, which auto-resolves to the matching company.
Status	`contact_status`	string	Writable	See Archiving and Deleting for the status values RevyOps sets and what each means.
Previous status	`previous_status`	string, nullable	Read-only	The status before the most recent change.
Status changed at	`status_changed_at`	string (date-time), nullable	Read-only	When `contact_status` last changed.
Do Not Contact	`do_not_contact`	string, nullable	Writable (v2 only)	Excludes the contact from future outreach, independent of `contact_status`. See Archiving and Deleting.
Origin	`origin`	string	Writable	Which platform the contact came from, for example `instantly`, `hubspot`, `closecrm`, or `revyops` for contacts created directly.
First/last campaign email sent, last reply received	`first_campaign_email_sent`, `last_campaign_email_sent`, `last_reply_received`	string (date-time), read-only	Read-only	Campaign engagement dates.
LinkedIn engagement fields (v2 only)	`total_linkedin_messages_sent`, `total_linkedin_message_replies`, `total_linkedin_inmails_sent`, `total_linkedin_connection_requests_sent`, `total_linkedin_connections_accepted`, and their matching first/last date fields	integer / string (date-time)	Read-only	LinkedIn outreach and reply counters, only on `/public/v2/contacts`.
Custom fields	`contact_custom_fields` (v1) / `contact_custom_fields_input` on write, `contact_custom_fields` on read (v2)	array of `{id, updated_time, field_name, field_value}`	Writable	See Custom Fields. `field_value` is capped at 2500 characters.

Relationships

Person: many-to-one. Every contact belongs to exactly one Person. RevyOps creates the person automatically the first time a contact is created, and links contacts for the same human together over time.
Company: many-to-one, optional. A contact can belong to at most one Company, set directly via company_id or resolved from the contact’s email domain.
Emails: one-to-many. Every outbound, inbound, and bounced email tied to this contact. See contact_id on the Emails endpoint.

Method	Endpoint	Description
GET	`/public/v2/contacts`	List and filter contacts
POST	`/public/v2/contacts`	Create a contact
GET	`/public/v2/contacts/{contact_id}`	Get one contact
PATCH	`/public/v2/contacts/{contact_id}`	Update a contact
DELETE	`/public/contacts/{contact_id}`	Permanently delete a contact
GET	`/public/contacts/lookup-by-custom-field`	Find contacts by a custom field’s value
POST	`/public/contacts/{contact_id}/custom-fields`	Add a custom field value
PATCH	`/public/contacts/{contact_id}/custom-fields/{field_id}`	Update a custom field value
DELETE	`/public/contacts/{contact_id}/custom-fields/{field_id}`	Remove a custom field value
GET	`/public/contacts-master-list`	List contacts across every client (master API key)

MCP tools: search_contacts, get_contact, update_contact (see MCP Tools). For filtering beyond an exact email or name match, use query_entity with entity: "contact".

Overview

Objects

Configuration

Attributes

Relationships

​Configuration

​Attributes

​Relationships

​Related Endpoints and MCP Tools

Configuration

Attributes

Relationships

Related Endpoints and MCP Tools