Skip to content

Contacts

A Contact (Ansprechpartner) is a person attached to exactly one business partner — a customer or a supplier. Contacts are managed via a single top-level resource so that adding or updating a contact does not require re-sending the entire parent payload.

The contact's parent is identified by parent_type (customer or supplier) plus parent_id — the parent's partner-supplied identifier (customer_id for customers, supplier_id for suppliers).

You can:

  • POST /contacts — bulk-upsert contacts. Async — returns a JobAck; poll GET /jobs/{job_id} for status. A single batch may mix customer and supplier contacts.
  • GET /contacts — cursor-paginated list, filterable by parent_type, parent_id, and is_active. Use modified_since for delta-sync.
  • GET /contacts/{id} — fetch one contact by its Mercura id (discoverable from GET /contacts list responses).
  • PATCH /contacts/{id} — partial update. Reassigning a contact to a different parent is not supported — delete and recreate.
  • DELETE /contacts/{id} — soft delete. The row stays in the database with is_active=false, so re-POSTing the same identity will reactivate it.
Operations

Upsert key

Each contact may carry its own optional external_id — the stable identifier from your source ERP (for example, Clage's ASP_ID). The upsert priority within a parent is:

  1. external_id when present on both sides — preferred because email and name can drift on the source system.
  2. email for contacts without an external_id.
  3. (name, phone) as a last resort for email-less contacts.

A row whose parent_type / parent_id cannot be resolved fails at the per-row level — the rest of the batch is unaffected.