Contacts
Endpoints
Section titled “Endpoints”| 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 |
The object
Section titled “The object”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 }] |
Create with organization links
Section titled “Create with organization links”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.
Upsert
Section titled “Upsert”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.
Link and unlink
Section titled “Link and unlink”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"Update, archive, delete
Section titled “Update, archive, delete”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”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.