Organizations
Endpoints
Section titled “Endpoints”| Method & path | Scope | Notes |
|---|---|---|
GET /organizations |
records:read |
Page list with q, filters, sort, fields, status |
POST /organizations |
records:write |
Create → 201. Duplicate → 409 DUPLICATE |
POST /organizations/upsert |
records:write |
Up to 100 items by domain, taxId, id or externalRef:<system> |
GET /organizations/:id |
records:read |
?expand=contacts,deals |
PATCH /organizations/:id |
records:write |
Partial update, optional version |
DELETE /organizations/:id |
records:delete |
Hard delete → 204. Prefer archiving |
GET /organizations/:id/timeline |
records:read |
Its activities and its contacts’ (activities) |
GET /organizations/:id/history |
records:read |
Audit events of the record (audit) |
The object
Section titled “The object”Common fields (id, version, status, tags, customFields, externalRefs, createdAt, updatedAt,
createdBy, updatedBy) plus:
| Field | Notes |
|---|---|
name |
Required, ≤ 200 |
domain |
Normalised: lower-case, no scheme, no www., no path. null for free-mail domains. Unique per account |
website |
A create with a website and no domain takes the domain from it |
taxId, country |
taxId upper-cased without spaces, dots or dashes; country ISO 3166-1 alpha-2. (country, taxId) is unique |
email |
The company’s generic inbox ([email protected]), lower-cased, ≤ 320. Not unique, free-mail allowed, never sets domain. Invalid → 400, reason INVALID_EMAIL |
city, address, industry, phone, linkedinUrl |
Free text |
description |
≤ 20 000 |
lifecycle |
lead (default), prospect, customer, partner, former_customer, other |
ownerUserId |
A user id or null |
lastContactedAt, lastActivityAt |
Read only, kept current by activities |
contactCount, openDealCount |
Read only |
Create
Section titled “Create”curl -s -X POST https://api.mety.ai/api/v1/organizations \ -H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \ -H "Idempotency-Key: org-acme-es" \ -d '{"name":"Acme Inmobiliaria","website":"https://www.acme.es/contacto","country":"ES","lifecycle":"prospect","tags":["inmobiliaria"]}'The domain becomes acme.es. Creating it again answers
409 DUPLICATE with details: { "field": "domain", "existingId": "…" }. Prefer the upsert when there is a
natural key.
Upsert
Section titled “Upsert”curl -s -X POST https://api.mety.ai/api/v1/organizations/upsert \ -H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \ -H "Idempotency-Key: import-2026-11-15-orgs-1" \ -d '{ "matchOn": "domain", "items": [ { "name": "Acme Inmobiliaria", "domain": "acme.es", "customFields": { "province": "Gipuzkoa" } }, { "name": "Ana Freelance", "domain": "gmail.com" } ] }'{ "data": [ { "index": 0, "result": "created", "id": "…" }, { "index": 1, "result": "error", "error": { "code": "MATCH_KEY_MISSING", "message": "…", "details": { "field": "domain", "reason": "FREE_MAIL_DOMAIN" } } } ]}Body: { matchOn, items: [≤ 100], nullOverwrites?: false }. Each item reports created, updated, unchanged or
error; one bad item does not fail the others, and items run in order (a later item matches what an earlier one
created).
- Without
nullOverwrites, missing or empty values never overwrite stored ones. tagsare a case-insensitive union;customFieldsandexternalRefsmerge key by key.- Item errors use the usual codes plus
MATCH_KEY_MISSING(the item lacks the match key;FREE_MAIL_DOMAIN: skip that organization) andAMBIGUOUS_MATCH(several records carry the external ref). - On the Free plan, an item that would create past the record limit is an item error with
PLAN_LIMIT_REACHED.
curl -s "https://api.mety.ai/api/v1/organizations/$ORG_ID?expand=contacts,deals" \ -H "Authorization: Bearer $METY_KEY"Update
Section titled “Update”curl -s -X PATCH https://api.mety.ai/api/v1/organizations/$ORG_ID \ -H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \ -d '{"lifecycle":"customer","customFieldsMerge":{"nextStep":"Renewal call in March"},"version":4}'nullclears a field.tags,customFieldsandexternalRefsreplace the whole value.customFieldsMerge: {…}merges instead (anullvalue removes that key).version(orIf-Match) guards against overwriting someone else’s change:409 VERSION_CONFLICT.
Archive, restore, delete
Section titled “Archive, restore, delete”# archive (reversible)curl -s -X PATCH https://api.mety.ai/api/v1/organizations/$ORG_ID \ -H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" -d '{"status":"archived"}'
# restorecurl -s -X PATCH https://api.mety.ai/api/v1/organizations/$ORG_ID \ -H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" -d '{"status":"active"}'DELETE /organizations/:id (needs records:delete) removes the record and its links; its activities stay.
Use it only for erasure requests and clear mistakes.
curl -sg "https://api.mety.ai/api/v1/organizations?q=acme&filter[lifecycle][in]=prospect,customer&sort=lastContactedAt:asc:nulls_first&fields=name,domain,lastContactedAt&perPage=100" \ -H "Authorization: Bearer $METY_KEY"q searches name, domain and email. Only active records are listed unless you filter on status
(status=archived or status=all). See lists, filters and search.