Skip to content

Conventions

https://api.mety.ai/api/v1
  • JSON in and out, camelCase field names. Send Content-Type: application/json. Bodies over 2 MB get 413 PAYLOAD_TOO_LARGE; malformed JSON gets 400 VALIDATION_FAILED.
  • Ids are UUID v4 strings generated by Mety.
  • Enums are lower-case strings (one_off, won).
  • Unknown body fields are 400. Read-only fields from a GET (id, createdAt, contactCount, lastContactedAt…) are ignored on write, so a read-modify-write is safe.
  • Every response carries X-Request-Id (yours if you sent one).
  • Health: GET https://api.mety.ai/api/health (liveness) and GET https://api.mety.ai/api/ready (readiness, 503 NOT_READY when not ready). Both return { data: { status, commit } }.
{ "data": { "id": "…", "name": "Acme" } }

Page lists (organizations, contacts, deals, feedback):

{ "data": [ … ], "meta": { "page": 1, "perPage": 50, "total": 137 } }

Cursor lists (activities, timelines, history, audit events):

{ "data": [ … ], "meta": { "nextCursor": "…" } }

nextCursor is null on the last page; pass it back as ?cursor=. Errors are always:

{ "error": { "code": "SCREAMING_SNAKE", "message": "Human readable, safe to show", "details": { … } } }

See errors for every code.

200 read or updated · 201 created · 204 deleted · 400 validation · 401 no or invalid credentials · 402 plan limit · 403 not allowed (scope) · 404 missing or another account’s · 409 conflict · 413 body over 2 MB · 422 domain rule broken · 429 rate limited · 503 not ready.

A missing id in the URL path is 404. A missing id in the body (for example organizations[0].organizationId) is 422 RELATED_RECORD_NOT_FOUND with details: { field, id }.

List kind Parameters
Page page (from 1), perPage (≤ 100, default 50). meta.total is the full count
Cursor limit (≤ 100; timelines default 30), cursor

Lists take filter[<field>][<op>]=<value>, sort=field:asc|desc[:nulls_first|nulls_last], q and fields=id,name,email. Details in lists, filters and search.

Organizations, contacts, deals and custom field definitions carry version (an integer from 1, incremented on every change). Send the version you last read:

Terminal window
curl -s -X PATCH https://api.mety.ai/api/v1/contacts/$CONTACT_ID \
-H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \
-d '{"jobTitle":"CEO","version":3}'

or as a header, If-Match: 3. If someone changed the record since, you get 409 VERSION_CONFLICT with the current record in details.current: re-apply your change on it and retry. Without version, the last write wins. A PATCH that changes nothing keeps the version and writes no audit event.

Every POST, PATCH and PUT accepts Idempotency-Key (1–200 characters). Use one for every write you might retry.

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: create-acme-2026-11-15" \
-d '{"name":"Acme Inmobiliaria","domain":"acme.es"}'
  • The first response is stored for 24 hours per (agent, key) and replayed to later requests with the same key, with the header Idempotent-Replayed: true. Client errors (4xx except 429) are stored too, so a retry gets the same error: fix the request and use a new key.
  • Same key, different request (method, URL, account or body): 422 IDEMPOTENCY_KEY_REUSED.
  • Same key while the first request is still running: 409 IDEMPOTENCY_IN_PROGRESS. Wait a second and retry with the same key.
  • Server errors (5xx) are not stored: a retry runs again.

Over MCP the same mechanism is the idempotencyKey tool argument.

Add ?dryRun=true to any write. Mety runs the whole write in a transaction, rolls it back, and returns what the response would have been with meta: { dryRun: true }. Nothing is stored and no email is sent. Dry runs are never stored for idempotency. Use it before every bulk change:

Terminal window
curl -s -X POST "https://api.mety.ai/api/v1/organizations/upsert?dryRun=true" \
-H "Authorization: Bearer $METY_KEY" -H "Content-Type: application/json" \
-d '{"matchOn":"domain","items":[{"name":"Acme","domain":"acme.es"}]}'
  • Upserts match by natural key: organizations domain | taxId | id | externalRef:<system>, contacts email | id | externalRef:<system>, deals id | externalRef:<system>. Re-running reports unchanged.
  • Activities dedupe by externalId (unique per account). Logging it again returns the existing activity with 200 and meta: { deduplicated: true }; only new links are added.
  • Creates of an existing domain, (country, taxId) or contact email answer 409 DUPLICATE with details: { field, existingId }. Uniqueness counts archived records too.

Integer minor units plus an ISO 4217 code: "amountCents": 480000, "currency": "EUR". Never floats. A deal’s currency defaults to the account’s baseCurrency. Totals are grouped per currency and never converted.

  • Timestamps are ISO 8601 UTC strings: 2026-11-15T09:30:00.000Z. You may send any offset (2026-10-02T09:14:00+02:00); Mety stores and returns UTC.
  • Date-only fields (expectedCloseOn, date custom fields): YYYY-MM-DD.
  • Relative times in filters (now-48h, today, start_of_month) use the account timezone.
  • An activity’s occurredAt may not be more than 5 minutes in the future.

Per agent: 20 requests per second and 1 200 per minute. A bulk request (an upsert or activity batch of up to 100 items) counts once. Over the limit:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
{ "error": { "code": "RATE_LIMITED", "message": "Too many requests. Slow down and retry later.", "details": { "retryAfterSeconds": 1 } } }

Wait Retry-After seconds, then retry. Prefer batches over many single calls.

On the Free plan, creating past a limit answers 402 PLAN_LIMIT_REACHED with details: { limit, max, plan, upgradeUrl }. Do not retry, and do not work around it (for example by deleting records). Finish the updates you can and pass the message to a person as is. In an upsert batch it is an item error and the other items still apply. See limits.