Buyer onboarding

Buyers are the starting point of every Novatrade24 transaction. A buyer in the API is a TradePartner entity acting in the buyer role, unique per (sellerId, vatNumber), so the same buyer across multiple orders is one record, not a new entry per deal. That identity covers COMPANY buyers, which is what this endpoint creates. Natural persons (type: "CONSUMER") are onboarded through the prospect / Click2Comply flow instead, which records no VAT number for them. They are read on the same operations as any other buyer, so branch on type rather than on the presence of vatNumber.

Upsert a buyer

POST /partners/{sellerId}/buyers is an upsert keyed on (sellerId, vatNumber):

First call → buyer created, 201 Created + Location header.
Second call with identical body → existing buyer returned, 200 OK.
Second call with different body → the same existing buyer, 200 OK, with notApplied naming the fields you sent that the record does not say. Nothing is overwritten; change a field with PATCH under If-Match.

curl -X POST "https://api.novatrade24.com/v1/partners/${SELLER_ID}/buyers" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "kycMode": "NT24_LED",
    "vatNumber": "DE123456789",
    "companyName": "AutoHandel Mustermann GmbH",
    "address": {
      "street": "Hauptstraße 42",
      "postCode": "10115",
      "city": "Berlin",
      "country": "DE"
    },
    "contacts": [
      {
        "firstName": "Erika",
        "lastName": "Mustermann",
        "email": "[email protected]"
      }
    ]
  }'

const buyer = await fetch(
  `https://api.novatrade24.com/v1/partners/${sellerId}/buyers`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Idempotency-Key': crypto.randomUUID(),
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      kycMode: 'NT24_LED',
      vatNumber: 'DE123456789',
      companyName: 'AutoHandel Mustermann GmbH',
      address: { street: 'Hauptstraße 42', postCode: '10115', city: 'Berlin', country: 'DE' },
      contacts: [{ firstName: 'Erika', lastName: 'Mustermann', email: '[email protected]' }],
    }),
  }
).then(r => r.json());

Response

{
  "uuid": "a1b2c3d4-...",
  "companyNumber": "NT-4K7M-9XQ2",
  "type": "COMPANY",
  "vatNumber": "DE123456789",
  "companyName": "AutoHandel Mustermann GmbH",
  "address": { ... },
  "kycMode": "NT24_LED",
  "status": "ACTIVE",
  "version": 0,
  "createdAt": "2026-04-22T10:00:00Z",
  "updatedAt": "2026-04-22T10:00:00Z"
}

Save the returned uuid, it’s the buyer reference for every subsequent call (order creation, KYC documents, invitations). The version field is for optimistic concurrency.

vatNumber is optional on a buyer response. Where the platform holds no VAT number for the buyer the key is absent, not null. companyNumber and type are always present.

Look a buyer up

GET /partners/{sellerId}/buyers resolves one buyer. Supply exactly one of vat or companyNumber, both matched exactly, ignoring case and surrounding whitespace:

curl "https://api.novatrade24.com/v1/partners/${SELLER_ID}/buyers?vat=DE123456789" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

curl "https://api.novatrade24.com/v1/partners/${SELLER_ID}/buyers?companyNumber=NT-4K7M-9XQ2" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Supplying neither or both is a 400. A value that resolves nothing is a 404, whatever its shape. A buyer for whom the platform holds no VAT number — a natural person, or a company that never supplied one — is reachable by companyNumber only. Which key resolved a buyer tells you nothing about what kind of party it is: read type on the response.

Buyers you reach through a shared KYC result

The platform holds one KYC record per buyer. You reach a buyer either because your partner made the KYC request, or because another partner that did shared the result with you. The split exists because the first request is billed differently — not because a shared record is a lesser one. So both routes give the same access. On a buyer you reach either way you can:

read it and list its contact people
add a contact person — POST .../contacts, and responsibleContact on an order reaches the same buyer through the same scope
correct companyName and the registered address under If-Match
block and unblock it

The two contact paths mean the same thing in every detail. Both match an existing person on the email address, compared trimmed and lower-cased, and both answer a differing name under that address the same way: the call resolves to the person on file and names the fields you sent that the record disagrees with, in notApplied. Neither overwrites the person on file. Send the same body to both and you get the same person; send a different one and both tell you so, in the same shape. Four consequences worth designing for:

Your edits land for everybody. Correcting a company name corrects it for every partner holding that record. That is the point — one clean record per buyer — but it means a PATCH is not a private change.
The tag moves without you. Another partner editing the same buyer advances its ETag, so a 409 on If-Match here does not mean you got something wrong. Re-read the buyer and retry — optimistic concurrency has the rules and the retry loop.
A replayed body can start reporting notApplied. Every write here compares your body against the record as it stands now, so once another partner or Novatrade24 has corrected a company name, an address or a contact person’s name or telephone number, the body that reported nothing yesterday reports it today. The call still succeeds and still resolves the same buyer or person — re-read the record and send what it says, or keep sending yours and ignore a report you already understand.
One VAT number can reach two buyers, and ?vat= gives you yours. If you reach a buyer through a share and then record your own under the same VAT number, both are yours to read — POST /buyers deliberately creates your own row rather than adopting the shared one. GET /buyers?vat= answers with your own record in that case, so a lookup followed by a PATCH corrects the row your orders point at. The shared record stays reachable by its uuid and by companyNumber. Storing the uuid a create returned is still the sturdier habit.

Blocking is the exception, and deliberately so: it is per-seller state. Blocking a buyer stops your trading with it and changes nothing for anybody else, and unblocking lifts your own block only. A share that has been revoked or has expired reaches nothing at all — the buyer answers 404 on reads and writes alike.

Choose a KYC mode

See the full KYC modes guide. Short version:

Mode	Who runs KYC	Output
MARKETPLACE_LED (A), not available yet	You / the marketplace	Raw documents + VIES check only
NT24_LED (B)	Novatrade24	Full iDenfy + AML + signed KYC profile PDF

Mode is required on buyer create, can be upgraded A→B (not reversed) via PATCH /buyers/{id}. Mode A is not available yet: MARKETPLACE_LED is rejected with 403 for every organization, and allowMarketplaceLedKyc reads false everywhere. Use NT24_LED.

Upload KYC documents

Documents are typed via the platform DocumentType enum. For a KYC buyer workflow, the relevant types are COC_*, BANK_*, VAT_*, CONTACT_*, ADDRESS_*, and TP_*.

curl -X POST "https://api.novatrade24.com/v1/partners/${SELLER_ID}/buyers/${BUYER_ID}/kyc/documents" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "type=COC_EXTRACT" \
  -F "documentDate=2026-01-15" \
  -F "file=@/path/to/coc-extract.pdf"

Documents are append-only: each upload is a new version. To supersede a bad upload, archive it:

curl -X PATCH "https://api.novatrade24.com/v1/documents/${DOC_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "status": "ARCHIVED" }'

The latest ACTIVE document of each type is what counts for compliance. The full history is retained for audit.

Trigger a VIES check

curl -X POST "https://api.novatrade24.com/v1/partners/${SELLER_ID}/buyers/${BUYER_ID}/kyc/vies-check" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)"

Returns 202 Accepted. Result is written to KYC status shortly after (async). Check GET .../kyc:

{
  "buyerId": "...",
  "kycMode": "NT24_LED",
  "overallStatus": "VALID",
  "viesLastCheckedAt": "2026-04-22T10:01:30Z",
  "viesResult": "VALID",
  "documentsComplete": true
}

Failing VIES checks (before or after pickup) also emit the kyc.vies_check_failed webhook, subscribe for real-time notification.

Optional: invite the buyer to complete their own KYC

If you don’t have all KYC data yourself, generate a self-service invitation the buyer receives an email with a branded upload link. The recipient must be the buyer’s company email or an active contact of the buyer (otherwise 422), and a KYC that is already decided takes no new invitation (409).

curl -X POST "https://api.novatrade24.com/v1/partners/${SELLER_ID}/buyers/${BUYER_ID}/kyc/self-service-invitations" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientEmail": "[email protected]",
    "expiresInDays": 14,
    "language": "de"
  }'

Response:

{
  "uuid": "inv_...",
  "kind": "KYC",
  "recipientEmail": "[email protected]",
  "status": "ACTIVE",
  "publicLinkUrl": "https://onboard.novatrade24.com/kyc/a1b2c3d4...",
  "createdAt": "2026-04-22T10:10:00Z",
  "expiresAt": "2026-05-06T10:10:00Z",
  "usageCount": 0
}

publicLinkUrl is in this response only: the platform keeps a hash of the link, so the list and a repeated create leave it out. To send a link again, revoke the invitation and create a new one. When the buyer uses the link, the self_service_invitation.used webhook fires. The KYC status endpoint reflects their submissions identically to API-uploaded documents, your integration doesn’t need to branch on data source.

NT24-led verification (Mode B only)

If the buyer’s kycMode is NT24_LED, trigger iDenfy + AML:

curl -X POST "https://api.novatrade24.com/v1/partners/${SELLER_ID}/buyers/${BUYER_ID}/kyc/verify" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)"

Returns the iDenfy session URL. Send that URL to the buyer; they complete the verification in-browser. NT24 fires kyc.verification_completed with the outcome (VERIFIED or REJECTED). Once verified, download the signed KYC profile PDF:

curl "https://api.novatrade24.com/v1/partners/${SELLER_ID}/buyers/${BUYER_ID}/kyc/profile" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -o kyc-profile.pdf

Block or unblock a buyer

Used for risk-based interventions (fraud signal, regulatory hold):

curl -X POST "https://api.novatrade24.com/v1/partners/${SELLER_ID}/buyers/${BUYER_ID}/block" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Manual review — possible VIN-cloning pattern" }'

Blocked buyers cannot have new orders created. Existing orders continue per their current state.

Inactive buyers

A buyer can close its account on Novatrade24. It then becomes inactive, and the buyer’s inactiveSince field carries the date; it is null while the buyer is active. Nobody learns why it closed. An inactive buyer stays readable: GET on the buyer, its KYC status and its orders keeps answering. Every write that names it answers 409 with a detail saying it is inactive:

creating an order for it, and resolving it again through POST /buyers
PATCH on the buyer, adding a contact, triggering a VIES check or a verification, uploading a KYC document, inviting it to self-service KYC
any write to one of its orders: update, cancellation, documents and payment

Naming a person at an inactive buyer does not bring that person back either. The same 409 applies when your own partner has closed its account.

KYC modes deep-dive

Differences between Marketplace-led and NT24-led.

Create an order

With a buyer in place, register your first transaction.

Contact details and manual identity checks

A business contact’s job title is optional, as it is on the platform. Other required contact details still apply before an identity check can start. When NT24 staff verified a contact’s identity manually, the KYC profile export shows “Identity verified manually by NT24 staff” with the date.

Get Started

Core Concepts

Integration Guide

Webhooks

Reference

Security & Compliance

Upsert a buyer

Response

Look a buyer up

Buyers you reach through a shared KYC result

Choose a KYC mode

Upload KYC documents

Trigger a VIES check

Optional: invite the buyer to complete their own KYC

NT24-led verification (Mode B only)

Block or unblock a buyer

Inactive buyers

Next

KYC modes deep-dive

Create an order

Contact details and manual identity checks

​Upsert a buyer

​Response

​Look a buyer up

​Buyers you reach through a shared KYC result

​Choose a KYC mode

​Upload KYC documents

​Trigger a VIES check

​Optional: invite the buyer to complete their own KYC

​NT24-led verification (Mode B only)

​Block or unblock a buyer

​Inactive buyers

​Next

KYC modes deep-dive

Create an order

​Contact details and manual identity checks

Upsert a buyer

Response

Look a buyer up

Buyers you reach through a shared KYC result

Choose a KYC mode

Upload KYC documents

Trigger a VIES check

Optional: invite the buyer to complete their own KYC

NT24-led verification (Mode B only)

Block or unblock a buyer

Inactive buyers

Next

Contact details and manual identity checks