Contacts

A contact is a person, and the unit that logs in: one login identity, one email, one role held inside its organization.

Two people at the same company are two contacts sharing an organization_id. A shared purchasing mailbox is one contact, not several. A contact with no organization is a standalone buyer, not an error.

curl "https://api.revenexx.com/v1/customers/contacts?limit=50" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..."

Listing and paging

Every column is an exact-match query filter (email, organization_id, registration_status, external_id, …). The list pages with limit (default 50, maximum 200) and offset, and sorts by one column with order=<column>.asc or .desc. The answer carries items and a page object with total (every row the filter matches), returned, offset and hasMore; page on until page.hasMore is false.

There is no updated_since filter and no range filter on any column. updated_at and source_synced_at match a timestamp exactly. To read what changed, sort with order=updated_at.desc and page until you reach a row you have already seen, or follow the contact.* events instead (as of 2026-10).

The list also filters on these columns, each an exact match (timestamps match exactly, too):

The row

A buyer may edit their own contact (PUT /v1/customers/contacts/{id}), except the fields the merchant keeps, their own role among them: changing one gets 403 (field_merchant_owned). On a colleague's contact, a buyer may change only the role, and needs the contacts.manage grant for it. The checks run in this order: a colleague outside the buyer's company, or a buyer without the grant, gets 403 (not_own_record); then any field besides role gets 403 (field_merchant_owned); then a role wider than the buyer's own, or a colleague who holds more than the buyer, gets 403 (role_exceeds_own). Only an edit that passes those checks meets self_service_master_data: set to addresses_only or none, it gets 403 (self_service_closed), on the buyer's own contact and on a colleague's alike. A call acts for a buyer when the storefront makes it on a signed-in buyer's behalf; a call that does not (an operator, an import, an ERP) is not refused for this reason.

A contact's own postal addresses are created on POST /v1/customers/addresses, described in Addresses on the Organizations page.

Creating one

curl -X POST https://api.revenexx.com/v1/customers/contacts \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{
        "email": "einkauf@example.com",
        "organization_id": "…",
        "role": "buyer",
        "first_name": "Anna",
        "last_name": "Berger"
      }'

email is the only field a create cannot omit. The create makes the person and their login together, so a contact created through this API can always sign in. registration_status may only be set to pending or approved here — a rejection has to carry a reason, and that is the reject route's job. A buyer acting for themselves gets 403 (self_service_closed) when they add a colleague under self_service_master_data set to addresses_only or none; a buyer without the contacts.manage grant gets not_self_service, and one naming another company's organization_id gets not_own_record, first, whatever the setting says. Inviting a colleague who already exists (POST /v1/customers/contacts/{contact_id}/invite) is a login, not master data, and is not refused for this reason.

Two rows of one tenant may not share an email.

A contact that cannot sign in

A contact written straight into the record by a migration or an ERP feed has no login: it reads as a customer everywhere, but the person cannot sign in or recover a password. POST /v1/customers/contacts/{contact_id}/identity creates the missing login and links it.

curl -X POST https://api.revenexx.com/v1/customers/contacts/{contact_id}/identity \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{"created_by": "erp-import-repair"}'

• Safe to re-run. A contact that already has a login is answered with it, created is false, and nothing changes. One call per imported contact heals a whole import.
• No password, no message. The call sends nothing. Invite the person (POST /v1/customers/contacts/{contact_id}/invite; its optional url sets where the message points and must be on one of the shop's link origins, else 422 link_origin_not_allowed; left out, the shop's first link origin is used), or point them at password recovery (POST /v1/customers/auth/recovery) to set their own password.
• It keeps refusals in place. A blocked contact, or one whose registration is pending or rejected, gets its login created disabled.
• 409 means a login already exists for that address but is linked to no contact, typically left over from a create that failed halfway. The call does not guess whether to link that login or remove it: that is your decision.

The activity timeline

contact_events is one entry on a customer's timeline: an activity somebody logged, or a registration decision the app recorded itself. Append-only — there is no update and no delete, which is what makes it usable as evidence. The one exception is erasing the person, which removes their timeline with them.

curl -X POST "https://api.revenexx.com/v1/customers/contacts/{contact_id}/events" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{
        "kind": "call",
        "subject": "Discussed Q3 framework agreement",
        "occurred_at": "2026-08-07T09:15:00Z",
        "actor": "sales@merchant.example",
        "payload": { "note": "Wants a second delivery address for the Leipzig site." }
      }'

Read the feed with the column the question needs:

curl "https://api.revenexx.com/v1/customers/contact_events?organization_id=…&order=occurred_at.desc&limit=50" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..."

Filter by contact_id for one person, organization_id for a whole company, kind for one type. Newest first is order=occurred_at.desc. The list also filters on assignee (the name the caller gave, exact match), and on due_at and done_at (exact timestamps only). A follow-up is a timeline entry with a due date; done_at stays null while it is open.

Read one entry by its id with GET /v1/customers/contact_events/{id}. It answers the entry as it was recorded; entries are never rewritten, apart from the done_at stamp a follow-up gets when it is closed. An unknown id is a 404.

Where documents go (contact points)

A contact point says where one kind of document goes for one company: the invoice to accounts payable, the order confirmation to the buyer who placed it, the shipping notice to goods-in, the dunning letter to whoever settles it. One point per company and kind is in use, flagged is_primary. The kinds come from recipient types, at GET /v1/customers/contact-point-kinds. Note the spelling: the kinds route is contact-point-kinds with hyphens, the contact points route is contact_points with an underscore.

When a buyer creates, changes or deletes a point that is not theirs, the call is refused with 403 (not_own_record). On an attributed call, changing a point of their own company also needs the organization.manage grant (Give buyer staff the right permissions); without it, or while the buyer's contact is still invited and has never signed in, the call is refused with 403 (not_self_service). An unknown id is a 404.

Those two checks come first on all three write routes (POST, PUT and DELETE). self_service_closed is the answer only for a buyer who owns the point and holds the grant, so a buyer without organization.manage gets not_self_service whatever the setting says.

Registration approval

The registration_mode setting decides what a self-registration is. It is a per-market setting in Cockpit, and a market that sets none follows the tenant default, so two markets of one tenant can differ. When it is approval_required, POST /v1/customers/auth/register creates an application: registration_status: "pending", status: "invited", the login exists with the applicant's own password but is disabled, and a newly founded organization is parked as blocked.

Two routes decide it.

Approve

curl -X POST "https://api.revenexx.com/v1/customers/contacts/{contact_id}/registration/approve" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{"decided_by":"sales@merchant.example"}'

Enables the login first — the password the applicant chose at submit time works immediately, no new credential is issued — then sets registration_status: "approved" and status: "active", and un-blocks the organization the registration itself founded. Writes a registration.approved timeline row and publishes contact.registration_approved.

The app itself sends the buyer no mail on approve or reject (as of 2026-10). A decision writes the timeline row, which publishes contact_event.created, and the contact.registration_* event. Telling the buyer is the job of whatever listens to those: a mail template in your tenant, or your own system through a webhook. Whether your tenant has such a template is not something the app decides. The registration_notification_recipients setting does not reach the buyer either: it lists your staff addresses, attached to the timeline row so the approval queue reaches the people who decide.

Reachable from pending or rejected: approving a rejection reinstates it. Approving an already-approved registration is a no-op, so a retry is safe.

Reject

curl -X POST "https://api.revenexx.com/v1/customers/contacts/{contact_id}/registration/reject" \
  -H "X-Revenexx-Tenant: <TENANT_SLUG>" \
  -H "X-Revenexx-Api-Key: rvxk_..." \
  -H "Content-Type: application/json" \
  -d '{"reason":"No verifiable VAT ID supplied.","decided_by":"sales@merchant.example"}'

Only reachable from pending. Sets registration_status: "rejected" and status: "blocked", and keeps the login in place but disabled — the email must not fall free for a silent second identity, and the merchant keeps the record. Delete the contact to send it to the trash with its login switched off; a second delete, emptying the trash or erasing the person removes both for good.

reason is mandatory. It is stored on the contact and carried in the event payload. Whether the applicant is ever told it is the tenant's registration_reason_disclosed setting, because that is a legal decision and not a template one.

Rejecting an already-rejected registration is a no-op. An approved registration cannot be rejected (409): blocking a live customer is a block, not a registration decision.

What the rejected buyer sees. A sign-in with the correct password answers 403 with code: "registration_rejected". An undecided application answers 403 with code: "registration_pending", and a wrong password stays 401. The reason is in the refusal's details.reason only when registration_reason_disclosed is on, and then the timeline row marks it disclosed. With it off (the default) the reason stays on the contact and the sign-in carries none. The contact.registration_rejected event always carries reason and a reason_disclosed flag, so a mail built from it has to honour the flag.

Account actions

These calls change a person's shop access, funnel stage or owner. Each row names what its timeline entry carries. The fields they change are the ones in the field table above: shop_access and access_blocked_reason follow from the calls below. shop_access is derived on every write and is never taken from a body. A revoked person reads shop_access: blocked with the reason in access_blocked_reason. A restored one reads can_order, unless the application is still undecided, which reads pending. The record, the role and the history stay. Only status, the login and access_blocked_reason change, and only for revoke and restore.

Contact lifecycle stages. The stage codes come from GET /v1/customers/contact-lifecycle-stages. GET /v1/customers/contact-lifecycle-stages/{id} reads one value. PUT changes its titles, help text, badge tone, position and default, and can retire it with active: false; the code cannot change. PUT with active: false retires a stage even while records carry it: they keep it, and pickers stop offering it. DELETE is the step that needs the stage unused: it answers 409 value_in_use while any record carries the code, and deleting the last stage answers a plain 409 with no code. The value lists page covers the full set of value endpoints.

Marketing consent. consent_marketing mirrors the consent app: true while the person holds at least one confirmed email subscription there. POST /v1/customers/consent-mirror/run reads the email subscriptions that changed in the last three hours and sets each person's flag to the consent app's current answer. The hourly schedule runs the same code, and so does each subscription event. It takes no body.

Trash and restore

DELETE /v1/customers/contacts/{id} moves a contact to the trash. The person's login is switched off and their sessions end, but the login is kept, so a restore needs no new invitation. It is refused with 409 (trash_blocked) while the person is the approver on a pending approval, and with 409 (primary_contact_required) while the person is the only primary contact of a company that has other people and the tenant requires a primary contact. A second DELETE on the same id deletes the contact for good, with its platform user. That is refused with 409 (delete_blocked) while another app still holds the person, such as an open order or quote, and the same primary-contact rule applies while the company is live. Deleting for good is an administrator's: a buyer's call gets 403 (purge_not_allowed).

A contact in the trash comes back with POST /v1/customers/contacts/{id}/restore, or is deleted for good by POST /v1/customers/contacts/trash/empty. Emptying the trash runs the same checks on each contact as a second DELETE, but a contact still blocked stays in the trash and is listed with its reason in the response, instead of the whole call answering 409. Restore needs the same right as the delete.

• Restore switches the login back on, unless the record says no: a blocked contact, or one whose registration is undecided, stays off.
• Refused with 409, parent_in_trash, while its organization is in the trash. The error's details.restore names the organization's restore route. Restoring the organization brings its contacts back with it.
• 409, not_in_trash, when the contact is not in the trash.
• 404 when no contact has that id.
• Emptying the trash deletes the contacts in the trash for good, oldest first, at most 50 per call. Each one is checked on its own, as a second DELETE would be. A contact that something still blocks stays in the trash and is listed in blocked with the reason. Call again while more is true. Emptying the trash is an administrator's right: a buyer's call is refused with 403, purge_not_allowed.

Reading and filtering the trash. GET /v1/customers/contacts takes trashed: exclude (the default) leaves trashed contacts out, only returns the trash alone and include returns the live and the trashed contacts together. Each contact carries the fields below, and each one is also an exact-match filter on the list call. A call that acts for a buyer always behaves as exclude, whatever trashed says. deleted_at and purge_at match only an exact timestamp; there is no range filter, so to see what was trashed in a period, sort with order and page.

The platform sets these fields when a contact is deleted and clears them when it is restored. They are information to read, so do not send them in a write.

The first delete fires contact.trashed and a restore contact.restored. contact.deleted fires only once the record is deleted for good. See Deletes and the trash.

Erase personal data

POST /v1/customers/contacts/{id}/erase answers a person's erasure request under Art. 17 GDPR. It skips the trash: the contact is deleted for good at once, in the trash or not, together with its platform user, its addresses and its timeline.

• The same checks as a final delete apply. Something still holding the person answers 409, delete_blocked, and details.blockers counts it. An open order keeps its buyer until it is closed. Being the only primary contact of an organization that requires one is also refused with 409.
• Documents already issued keep their own snapshot in the apps that hold them.
• history_pseudonymised in the answer says whether the person was also pseudonymised in the record history. It is false, because this call does not do that yet (as of 2026-10).
• Merchants only. A buyer's call is refused with 403, purge_not_allowed: an erasure request is carried out by the merchant.

Where to go next

• Organizations — the company a contact belongs to.
• Roles and permissions — what role grants.
• Storefront accounts — where a registration comes from.
• Value lists — the activity types kind draws on.