Skip to content
/
Public Contacts Bulk Upse...

Public Contacts Bulk Upsert

Request

Bulk-upsert contacts (async).

Each row carries its own parent_type (customer or supplier) and parent_id (the parent's partner-supplied identifier — customer_id for customers, supplier_id for suppliers). A single batch may mix both kinds.

Upsert key. When external_id is set on a contact it is the primary upsert key against the parent. Without it, the worker falls back to dedup by email, then (name, phone) — same priority as the internal ERP sync path. Rows whose parent cannot be resolved fail at the per-row level and surface in the job's errors[]; the rest of the batch is unaffected.

Response.

  • 202 Accepted with JobAck { job_id, status_url } on the first call.
  • 200 OK with the same JobAck on an idempotent replay.

Idempotency. Pass an Idempotency-Key header (≤ 255 chars). Same key with a different body returns 422 IDEMPOTENCY_KEY_MISMATCH.

Headers
authorizationstring or null(Authorization)

Bearer <mrc_live_…> API key

Idempotency-Keystring or null(Idempotency-Key)

Optional client-supplied key for safe retries; <= 255 chars

Bodyapplication/jsonrequired
contactsArray of objects, [ 1 .. 100000 ] items(Contacts)required
Example:
[
  {
    "email": "t.weber@mustermann-elektro.example",
    "external_id": "ASP-00815",
    "is_default": true,
    "name": "Thomas Weber",
    "parent_id": "K-10042",
    "parent_type": "customer",
    "phone": "+49 211 5551020"
  }
]
curl -i -X POST \
  https://docs.mercura.ai/_mock/openapi/contacts \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'authorization: string' \
  -d '{
    "contacts": [
      {
        "email": "t.weber@mustermann-elektro.example",
        "external_id": "ASP-00815",
        "is_default": true,
        "name": "Thomas Weber",
        "parent_id": "K-10042",
        "parent_type": "customer",
        "phone": "+49 211 5551020"
      }
    ]
  }'

Responses

Idempotent replay — same job returned

Bodyapplication/json
job_idstring(Job Id)required
Example:"4242"
status_urlstring(Status Url)required

Relative URL to poll for this job's status

Example:"/api/public/v1/jobs/4242"
Response
{
  "job_id": "4242",
  "status_url": "/api/public/v1/jobs/4242"
}