Contacts

71 operations. Call each with POST https://app.chirply.io/api/v1/actions/<name> and a bearer token; the response is { "data": { "action", "summary", "result" } }. A read badge means the operation changes nothing; write requires the credential’s write scope.

Add contact email address

contacts.add_email_addresswrite

Add an email address to a contact. It becomes primary automatically when it is the contact's first address; pass primary=true to make it the address campaigns, automations and merge tokens send to. Saves CRM data only — it sends nothing and costs nothing. Refused if the address already belongs to a different contact in this account, since one address identifies one person.

Parameters

Field	Type	Required	Description
contact_id	string (uuid)	required	The contact receiving the email address.
email	string	required	The email address to save.
label	string (or null)	optional	Optional free-text label — "work", "billing", "old Gmail". Null or omitted means unlabelled.
primary	boolean	optional	Make this the primary address. The first address becomes primary regardless of this value. Default: false

Example

curl -X POST https://app.chirply.io/api/v1/actions/contacts.add_email_address \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11",
    "email": "ada@example.com"
  }'

Field	Type	Required	Description
body	string	required	The note text.
contact_id	string (uuid)	optional	Contact to attach the note to.
company_id	string (uuid)	optional	Company to attach the note to.
deal_id	string (uuid)	optional	Deal to attach the note to.

Field	Type	Required	Description
contact_ids	array of (string (uuid))	required	Contact ids to act on. Ids outside this org are ignored.
tag_ids	array of (string (uuid))	required	Tag ids to add (create them first with contacts.create_tag).

Field	Type	Required	Description
id	string (uuid)	optional	The contact to assemble context for. Provide this OR context_token.
context_token	string	optional	A short-lived handoff token minted by the tracking script's chirply.getContext() (its `contextToken` field). Redeem it here to load the visitor a page just identified, without the browser ever seeing the internal contact id. Only the account the token was minted FOR can redeem it. Provide this OR id.
include_transcripts	boolean	optional	Include condensed text of past-call transcripts. Turn off for a lighter, less-sensitive bundle that keeps only call summaries and outcomes. Default: true
include_web	boolean	optional	Include the contact's website-tracking activity (first-touch attribution, page-view totals, and recent page views). Default: true

Field	Type	Required	Description
phone_number_id	string (uuid)	required	One of the account's phone numbers, from numbers.list.
owner_user_id	string (uuid) (or null)	required	The teammate to assign them to, from team.list_members, or null to clear the owner on all of them.
limit	integer	optional	Most contacts to assign in one call, from one to five thousand. A line with more history than this assigns the most recent and reports how many were left, so run it again to continue. Default: 2000

Field	Type	Required	Description
first_name	string	optional	Given name.
last_name	string	optional	Family name.
business_name	string	optional	Business name — the display name for company-shaped leads.
facebook_id	string	optional	Stable Facebook person/friend id. Unique within this organization.
email	string (email)	optional	Email address. Unique within this organization — it identifies the person.
phone	string	optional	Phone number, in any format; normalized to E.164 before it is stored. Unique within this organization — it identifies the person.
website	string	optional	Website URL.
yelp_url	string	optional	Public Yelp listing URL for this business, e.g. https://www.yelp.com/biz/… Kept separate from `website` because a Yelp-sourced lead often has no site of its own.
title	string	optional	Job title.
birthday	string (date)	optional	Date of birth as YYYY-MM-DD. Birthday automations recur from its month and day.
source	string	optional	Where this contact came from — a channel slug shown on their record and used by the Source filter. One of: referral, phone_call, walk_in, event, advertisement, social_media, staff (a person typed them in), other. Defaults to `api`, meaning this call created them; set it when you know better, because a contact whose origin reads 'Unknown' is one nobody trusts.
source_detail	map of string → object	optional	The specifics behind `source`, shown as a line under it on the record — e.g. {"note": "referred by Dana Ortiz"}. Free-form; short strings only.
lifecycle	string	optional	Lifecycle stage key, e.g. 'lead', 'trial', 'active', 'customer', 'churned'. The org defines its own set — call contacts.list_lifecycles for the valid keys. Default: "lead"
company_id	string (uuid)	optional	Company this contact works at.
owner_id	string (uuid)	optional	User id of the team member who owns the relationship.
address	object	optional	Postal address with separate street, city, state, and ZIP / postal code fields.
address.line1	string	optional	Street address.
address.line2	string	optional	Suite / unit.
address.city	string	optional	City.
address.state	string	optional	State or province.
address.postal_code	string	optional	ZIP / postal code.
address.country	string	optional	Country.
notes	string	optional	Free-text notes on the record, visible to the whole account.
custom	map of string → object	optional	Custom-field values keyed by `custom_field_defs.key` (see contacts.list_fields). Replaces the whole blob — send the merged object.

Field	Type	Required	Description
entity	"contact" \| "company" \| "deal"	required	Which record type the field lives on.
label	string	required	The field label shown in the app.
type	"text" \| "textarea" \| "number" \| "date" \| "select" \| "multiselect" \| … 3 more	optional	How the value is entered and rendered. "user" (Team member) holds one account member — their user id — and is available on deals only. Default: "text"
options	string[]	optional	Choices for select/multiselect fields. Default: []
required	boolean	optional	Whether the app's form requires it. Default: false

Field	Type	Required	Description
fields	object[]	required	The contact custom fields to create.
fields[].label	string	required	Field label, usually the CSV column header.
fields[].type	"text" \| "textarea" \| "number" \| "date" \| "select" \| "multiselect" \| … 3 more	optional	How imported values should be stored and rendered. Not "user" — Team member fields are deals-only. Default: "text"

Field	Type	Required	Description
name	string	required	The tag name.
color	string	optional	Hex colour the tag renders in, e.g. '#64748b'. Default: "#64748b"

Field	Type	Required	Description
id	string (uuid)	required	The contact to write to.
instruction	string	optional	Optional steer, e.g. 'mention the demo next week'.
channel	"email" \| "sms"	optional	What the draft is for. 'email' also returns a subject line and writes at email length; 'sms' (the default) returns a message body only.

Field	Type	Required	Description
workflow_id	string (uuid)	required	The workflow (automation) to run.
contact_ids	array of (string (uuid))	required	Contact ids to act on. Ids outside this org are ignored.

Field	Type	Required	Description
contact_ids	array of (string (uuid))	required	Contact ids to act on. Ids outside this org are ignored.
subject	string	required	The subject line. Supports merge fields, e.g. {{first_name}}.
body	string	required	The message body. Supports merge fields, e.g. {{first_name}}.
email_identity_id	string (uuid) (or null)	optional	Which of the account's verified sending addresses to send FROM (see email_routing capabilities). Omit or null to use each contact's own sender preference, falling back to the account default address. Ignored when email_pool_id is set.
email_pool_id	string (uuid) (or null)	optional	Send through an email pool instead of one address, rotating across its members least-used-first and steering every reply to the pool's reply-to. Wins over email_identity_id. The pool's warmup allowance caps how much goes out per day.
include_signature	boolean	optional	Append the sender's email signature to every message, exactly as a one-to-one reply would. Defaults to true. Set false for a send that already carries its own sign-off. Default: true
start_at	string (date-time) (or null)	optional	When this should START, as an ISO 8601 timestamp with a timezone (e.g. 2026-08-20T14:00:00Z). Omit or null to start immediately. A time in the past starts immediately. The job waits in the account's Jobs list until then and can be rescheduled or canceled before it starts.
per_minute	integer (or null)	optional	Cap on items sent per minute. null removes the per-minute cap.
per_hour	integer (or null)	optional	Cap on items sent per hour. null removes the per-hour cap.
per_day	integer (or null)	optional	Cap on items sent per day. null removes the per-day cap.

Field	Type	Required	Description
contact_id	string (uuid)	required	Contact in this account whose communication history to read.
section	"summary" \| "messages" \| "calls" \| "ai_calls" \| "live_chat" \| "campaigns"	optional	Lifetime totals or a page of complete stored communication records, including website live chat and campaign delivery ledgers. Campaigns do not retain exact delivered message bodies. Default: "summary"
agent_id	string (uuid)	optional	Optional AI agent in this account; adds this agent's cumulative session duration and active sessions to the summary.
offset	integer	optional	Row offset from next_offset; advance only after all character pages are read. Default: 0
character_offset	integer	optional	Character offset from next_character_offset for the same row; reset to zero when advancing rows. Default: 0

Field	Type	Required	Description
csv	string	required	The CSV text, header row first. Quoted fields and embedded newlines are handled.
file_name	string	optional	What to call this import on each contact's record, e.g. 'jan-tradeshow.csv'. Shown under their source.
mapping	map of string → string	optional	Override the automatic header matching: {"<header in the file>": "<contact field>"}. Fields: full_name, first_name, last_name, business_name, email, phone, website, yelp_url, title, address, street, city, state, postal_code, notes, lifecycle, created_at, created_at_overwrite, or custom.<key> for a custom field. full_name splits the first word into first_name and stores the remainder as last_name. street, city, state, and postal_code populate the structured address; address stores a one-column address as its street line. Map a header to an empty string to skip that column. Headers you don't list keep their automatic match.
tag_ids	array of (string (uuid))	optional	Tags applied to every contact this import touches, new and matched.
list_ids	array of (string (uuid))	optional	Static contact lists every new or matched contact should join.
owner_id	string (uuid)	optional	Owner for the imported contacts.
lifecycle	string	optional	Lifecycle for the imported contacts; defaults to lead.

Field	Type	Required	Description
limit	integer	optional	Max rows to return (1–100). Default: 25
offset	integer	optional	Rows to skip. Default: 0
query	string	optional	Text to match in first/last name, business name, email, phone, city, state, or ZIP / postal code.
city	string	optional	Filter contacts whose city contains this text.
state	string	optional	Filter contacts whose state or province contains this text.
postal_code	string	optional	Filter contacts whose ZIP or postal code contains this text.
phone_types	array of ("mobile" \| "landline" \| "voip" \| "tollFree" \| "other" \| "unknown" \| … 1 more)	optional	Primary phone types to include: mobile, landline, voip, tollFree, other, unknown (including not yet looked up), or none (no primary phone). Uses the saved type, then existing lookup cache; no paid lookup is performed.
ltv_min_cents	integer	optional	Inclusive minimum lifetime value after refunds, in minor currency units. Zero includes contacts with no payments. Combined connected-account totals may mix currencies.
ltv_max_cents	integer	optional	Inclusive maximum lifetime value after refunds, in minor currency units. Must be at least ltv_min_cents when both are supplied.
lifecycle	string	optional	Only contacts at this lifecycle stage.
lifecycles	string[]	optional	Contacts at any of these lifecycle stages. Combined with `lifecycle` when both are supplied.
is_customer	boolean	optional	Filter by customer status: true = only customers (they have bought from us), false = only non-customers. Omit for all. This is separate from `lifecycle` — a churned contact can still be a customer.
company_id	string (uuid)	optional	Only contacts at this company.
company_ids	array of (string (uuid))	optional	Contacts at any of these companies. Values are ORed.
owner_id	string (uuid)	optional	Only contacts owned by this user.
owner_ids	array of (string (uuid))	optional	Contacts owned by any of these users. Values are ORed.
source	string	optional	Only contacts that arrived through this channel, e.g. 'website', 'Outscraper', 'Yelp', 'facebook_lead_ad', 'unknown'. Call contacts.list_sources to see which ones this org actually has.
sources	string[]	optional	Contacts that arrived through any of these source channels. Values are ORed.
tag_ids	array of (string (uuid))	optional	Contacts carrying any of these tags. Tag filtering stacks with every other supplied filter.
list_ids	array of (string (uuid))	optional	Contacts that belong to any of these static lists. List filtering stacks with every other supplied filter.
sort	"name" \| "contact" \| "email" \| "phone" \| "website" \| "title" \| … 10 more	optional	Which column orders the result, matching the contact list's own column headers: 'ltv' (lifetime value), 'created_at' (when they were added, the default), 'updated_at', 'name', 'email', 'phone', 'website', 'title', 'business_name', 'facebook_id', 'city', 'state', 'source', 'lifecycle', 'customer', or 'contact' (the email/phone stack, ordered by email).
direction	"asc" \| "desc"	optional	Which way to order. Omit for each column's natural direction — money and dates come back highest/newest first, text A to Z.
include_revenue	boolean	optional	When true, add each contact's Stripe money, unified by email across EVERY connected Stripe account: `lifetime_value_cents` (net of refunds, minor units), `mrr_cents` (monthly run-rate of their active subscriptions), `stripe_currencies` (the currencies seen — more than one means the total mixes currencies and is indicative), and `stripe_accounts_count` (how many of your Stripe accounts they've paid). Contacts with no Stripe history report zeros. Off by default because it costs an extra lookup.

Field	Type	Required	Description
keep_id	string (uuid)	required	The contact that survives. It keeps its id, so anything already linking to it still works, and its own non-blank values win over the others'.
merge_ids	array of (string (uuid))	required	The contacts to fold in and then delete — up to 9. Ids equal to keep_id, or already absorbed by an earlier merge in the same call, are skipped rather than treated as an error.
primary_email	string (or null)	optional	Which address the merged contact should send from, as text. Must be one the merged contact ends up holding; anything else is ignored. Omit to keep whatever the surviving contact already used.
primary_phone	string (or null)	optional	Which number calls and texts should go to, as text. Must be one the merged contact ends up holding; anything else is ignored. Omit to keep whatever the surviving contact already used.

Field	Type	Required	Description
key	string	required	Stable lifecycle key returned by contacts.list_lifecycles.
label	string	required	New stage name people will see.

Field	Type	Required	Description
field	"listIds" \| "tagIds" \| "sources" \| "ownerIds" \| "companyIds"	required	Filter directory to search: listIds, tagIds, sources, ownerIds or companyIds.
query	string	optional	Case-insensitive text within an option name. Empty text returns the first page. Default: ""
offset	integer	optional	Rows to skip, in steps of 20 for subsequent pages. Default: 0
selected	string[]	optional	Optional selected option values to resolve to labels; searches and offset are ignored when this is supplied. Default: []

Field	Type	Required	Description
id	string (uuid)	required	The contact to block or unblock.
blocked	boolean	optional	True blocks and hides the contact; false restores them. Default: true

Field	Type	Required	Description
id	string (uuid)	required	The contact to edit.
first_name	string (or null)	optional	Given name.
last_name	string (or null)	optional	Family name.
business_name	string (or null)	optional	Business name — the display name for company-shaped leads.
facebook_id	string (or null)	optional	Stable Facebook person/friend id. Null clears it.
email	string (email) (or null)	optional	Email address. Null clears it; moving one that belongs to another contact in this org fails with a conflict.
phone	string (or null)	optional	Phone number, in any format. Null clears it; moving one that belongs to another contact in this org fails with a conflict.
website	string (or null)	optional	Website URL.
yelp_url	string (or null)	optional	Public Yelp listing URL. Null clears it.
title	string (or null)	optional	Job title.
birthday	string (date) (or null)	optional	Date of birth as YYYY-MM-DD. Null clears it.
source	string (or null)	optional	Where this contact came from — the channel slug behind the Source filter (referral, phone_call, walk_in, event, advertisement, social_media, staff, other, or a machine one like website / google_maps). Only change it when the current value is wrong; it is provenance, not a note field.
source_detail	map of string → object (or null)	optional	The specifics behind `source`, shown as a line beneath it — e.g. {"note": "referred by Dana Ortiz"}. Replaces the whole object.
lifecycle	string	optional	New lifecycle stage key. Changing it fires the org's 'Lifecycle changed' automations, which can message this person for real.
company_id	string (uuid) (or null)	optional	Company this contact works at.
owner_id	string (uuid) (or null)	optional	User id of the team member who owns the relationship, or null to leave it unowned. Changing it fires the org's 'Owner changed' automations.
address	object (or null)	optional	Postal address with separate street, city, state, and ZIP / postal code fields.
address.line1	string	optional	Street address.
address.line2	string	optional	Suite / unit.
address.city	string	optional	City.
address.state	string	optional	State or province.
address.postal_code	string	optional	ZIP / postal code.
address.country	string	optional	Country.
notes	string (or null)	optional	Free-text notes on the record, visible to the whole account.
custom	map of string → object	optional	Custom-field values keyed by `custom_field_defs.key` (see contacts.list_fields). Replaces the whole blob — send the merged object.

Field	Type	Required	Description
id	string (uuid)	required	The field definition to edit.
label	string	optional	New label.
type	"text" \| "textarea" \| "number" \| "date" \| "select" \| "multiselect" \| … 3 more	optional	New field type. "user" (Team member) is accepted only on a deal field.
options	string[]	optional	New select/multiselect choices.
required	boolean	optional	Whether the app's form requires it.

Field	Type	Required	Description
id	string (uuid)	required	The tag to edit.
name	string	optional	New tag name.
color	string	optional	New hex colour.

Add contact email address

Parameters

Example

Add a note

Parameters

Example

Add phone number

Parameters

Example

Tag contacts

Parameters

Example

Get AI context

Parameters

Example

Assign to a teammate

Parameters

Example

Assign everyone who uses a line

Parameters

Example

Delete selected contacts

Parameters

Example

Email many contacts at once

Parameters

Example

Load contact action options

Parameters

Example

Text many contacts at once

Parameters

Example

Brief me before I call

Parameters

Example

Get communication context

Parameters

Example

Create a contact

Parameters

Example

Create a custom field

Parameters

Example

Create custom fields for unmapped columns

Parameters

Example

Create lifecycle stage

Parameters

Example

Create a tag

Parameters

Example

Delete a contact

Parameters

Example

Remove contact email address

Parameters

Example

Delete a custom field

Parameters

Example

Delete lifecycle stage

Parameters

Example

Remove phone number

Parameters

Example

Delete a tag

Parameters

Example

Draft a follow-up

Parameters

Example

Add contacts to automation

Parameters

Example

Find a contact by Facebook ID

Parameters