Skip to content

Organizations

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)

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
Terminal window
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.

Terminal window
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.
  • tags are a case-insensitive union; customFields and externalRefs merge 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) and AMBIGUOUS_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.
Terminal window
curl -s "https://api.mety.ai/api/v1/organizations/$ORG_ID?expand=contacts,deals" \
-H "Authorization: Bearer $METY_KEY"
Terminal window
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}'
  • null clears a field.
  • tags, customFields and externalRefs replace the whole value. customFieldsMerge: {…} merges instead (a null value removes that key).
  • version (or If-Match) guards against overwriting someone else’s change: 409 VERSION_CONFLICT.
Terminal window
# 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"}'
# restore
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":"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.

Terminal window
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.