Skip to main content
POST
Add a contact person to the buyer.

Authorizations

Authorization
string
header
required

OAuth 2.0 client_credentials grant via Keycloak service account. Clients are provisioned per IntegrationOrganization in the nt24-idp realm.

Headers

Idempotency-Key
string
required

Client-generated unique key (UUID recommended) for this write operation. Identical key + identical body within 24h returns the cached response. Identical key + different body returns 422.

Required string length: 1 - 255
X-Purpose
string

Optional purpose justification for PII-bearing endpoints. May become mandatory for sensitive data in a future release.

Path Parameters

sellerId
string<uuid>
required

UUID of the seller trade partner (must be in caller's authorized list).

buyerId
string<uuid>
required

UUID of the buyer trade partner.

Body

application/json
firstName
string
required
lastName
string
required
email
string<email>
required
phone
string
role
enum<string>

The account permission asked for on the platform: OWNER (Admin) or CONTACT (Member). Optional. Granted under the platform's rules, and named in notApplied when the person does not end up with it — see POST /partners/{sellerId}/buyers/{buyerId}/contacts. Any other value is refused with 422.

Available options:
OWNER,
CONTACT

Response

The contact person this body resolves to — newly recorded, or the one already on file under that email address. notApplied names the fields the body disagreed with, and is absent when there were none.

uuid
string<uuid>
required
firstName
string
required
lastName
string
required
email
string<email>
required
phone
string
createdAt
string<date-time>
notApplied
string[]

Fields of the request that named something other than what the person already recorded under this email address says, and were therefore not written — firstName, lastName, phone — and role when the person did not get the role asked for, whether newly recorded or already on file. email is never listed: it is the key the two were matched on.

Present only on POST /contacts, and only when there was something to report. Absent on every read, on a newly recorded person who got the role asked for, and on a replay that agreed with the record.

The rest of the body carries the person as this record holds them, so you can see who your call resolved to. Nothing here is applied: a stored contact person is never overwritten through this API.