Skip to content

Contacts

Method & path Scope Notes
GET /contacts records:read Page list with q, filters, sort, fields, status; shortcut organizationId=
POST /contacts records:write Create → 201. Duplicate email → 409 DUPLICATE
POST /contacts/upsert records:write Up to 100 items by email, id or externalRef:<system>
GET /contacts/:id records:read ?expand=deals
PATCH /contacts/:id records:write Partial update, optional version
DELETE /contacts/:id records:delete Hard delete → 204
PUT /contacts/:id/organizations/:organizationId records:write Link (or update the link): { role?, isPrimary? } → 200 contact
DELETE /contacts/:id/organizations/:organizationId records:write Unlink → 204
GET /contacts/:id/timeline records:read Its activities
GET /contacts/:id/history records:read Audit events

Common fields plus:

Field Notes
firstName, lastName, email At least one is required. email is lower-cased and unique per account
fullName Derived, read only
phone, jobTitle, linkedinUrl, description Free text
lifecycle lead (default), prospect, customer, partner, former_customer, other
doNotContact Boolean, default false. Respect it
ownerUserId A user id or null
lastContactedAt, lastInboundAt, lastOutboundAt, lastActivityAt Read only, kept current by activities
organizations [{ organizationId, name, domain, role, isPrimary }]
Terminal window
curl -s -X POST https://api.mety.ai/api/v1/contacts \
-H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: contact-laura-acme" \
-d '{
"firstName": "Laura", "lastName": "Pérez", "email": "[email protected]", "jobTitle": "CEO",
"organizations": [{ "organizationId": "'"$ORG_ID"'", "role": "CEO" }]
}'

The first link becomes primary unless you send isPrimary: false. Setting isPrimary: true on a link unsets the others; removing the primary promotes the oldest remaining link.

Terminal window
curl -s -X POST https://api.mety.ai/api/v1/contacts/upsert \
-H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: gmail:THREAD_ID:contacts" \
-d '{
"matchOn": "email",
"items": [
{ "email": "[email protected]", "firstName": "Laura", "lastName": "Pérez",
"organizations": [{ "organizationId": "'"$ORG_ID"'", "role": "CEO" }] }
]
}'

Same rules as the organization upsert: no empty overwrites without nullOverwrites, tags union, customFields/externalRefs merge, per-item results. Links in organizations are added, never removed.

Terminal window
curl -s -X PUT https://api.mety.ai/api/v1/contacts/$CONTACT_ID/organizations/$ORG_ID \
-H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \
-d '{"role":"Board member","isPrimary":false}'
curl -s -X DELETE https://api.mety.ai/api/v1/contacts/$CONTACT_ID/organizations/$ORG_ID \
-H "Authorization: Bearer $METY_KEY"

As for organizations: null clears, tags/customFields/externalRefs replace, customFieldsMerge merges, version or If-Match guards. Archive with PATCH { "status": "archived" }. DELETE (records:delete) removes the contact and its links; activities stay.

List: who has not been contacted in 48 hours

Section titled “List: who has not been contacted in 48 hours”
Terminal window
curl -sg "https://api.mety.ai/api/v1/contacts?filter[lifecycle][in]=lead,prospect&filter[doNotContact][eq]=false&filter[lastContactedAt][lt_or_null]=now-48h&sort=lastContactedAt:asc:nulls_first&fields=fullName,email,lastContactedAt,organizations" \
-H "Authorization: Bearer $METY_KEY"

q searches name and email. lt_or_null also matches contacts never contacted. See lists, filters and search.