> ## Documentation Index > Fetch the complete documentation index at: https://developers.novatrade24.com/llms.txt > Use this file to discover all available pages before exploring further. # Lookup buyer by VAT number or company number. > Resolves exactly one buyer of this seller. Supply **exactly one** of `vat` or `companyNumber`; neither and both are both `400`. `companyNumber` is the Novatrade24 partner number, which every buyer has. `vat` matches on the buyer's VAT number alone, so a buyer for whom the platform holds none — a natural person, or a company that never supplied one — is reachable by `companyNumber` only. Which key resolved a buyer says nothing about what kind of party it is: read `type` on the response. Either value is matched exactly, ignoring case and surrounding whitespace. There is no partial or fuzzy matching: a prefix of a real number is a miss, not a hit. A value of the wrong shape is a miss too, not a validation error. A VAT number is not unique, so it can reach both a buyer you recorded yourself and one you reach through another partner's shared KYC result. Where it reaches both, this answers with **your own** record — the one your orders point at and the one a `PATCH` from you should correct. The shared record stays reachable by `companyNumber` and by its `uuid`. ## OpenAPI ````yaml /openapi-integration-v1.yaml get /partners/{sellerId}/buyers openapi: 3.1.0 info: title: Novatrade24 Integration API version: 1.5.0-draft summary: Customer-facing integration API for the Novatrade24 compliance platform. description: > The Novatrade24 Integration API lets marketplaces, dealers, and financial partners embed EU VAT-compliant cross-border vehicle transactions into their own systems. The API is organized around the end-to-end compliance workflow: 1. **Buyer (KYC)**: create or sync a buyer, run VIES, upload KYC documents, optionally trigger NT24-led verification. 2. **Order**: register a VIN-based transaction linked to a buyer. 3. **Invoice**: submit VAT security deposit invoice (`PRELIMINARY`) and final invoice data and documents. 4. **Payment**: submit proof-of-payment; pickup readiness is derived from it. 5. **Transport**: confirm pickup and delivery with CMR / declarations. 6. **Compliance rollup**: poll the composed state of the five modules above, or subscribe to webhooks. The rollup is also where you see what is still missing: `blockers[]` names the artifact and the module waiting for it. There is no seventh step. Novatrade24 staff close an order once the artifacts are on file; the rollup reports that as `complianceStatus: VALID`. The final invoice is submitted through the invoice operation with `type: FINAL`, like the VAT security deposit invoice (`PRELIMINARY`). **Status:** Draft specification. The production endpoint `https://api.novatrade24.com/v1` is live, with access restricted to pilot customers: every request needs a bearer token obtained through the OAuth2 client credentials grant. A hosted mock is available at `https://mock.api.novatrade24.com` for integration design. termsOfService: https://novatrade24.com/terms-and-conditions contact: name: Novatrade24 Integration Support email: integration-support@novatrade24.com url: https://developers.novatrade24.com license: name: Proprietary url: https://novatrade24.com/terms-and-conditions servers: - url: https://api.novatrade24.com/v1 description: Production (pilot, restricted access) - url: https://api.stage.novatrade24.com/v1 description: Staging environment - url: https://mock.api.novatrade24.com description: Hosted mock server (Prism), spec-driven stub responses security: - oauth2ClientCredentials: [] tags: - name: Discovery description: Organization + capability discovery. - name: Buyers description: | Manage buyer (trade partner) records and KYC lifecycle. `COMPANY` buyers are upserted by `(sellerId, vatNumber)`. Natural-person (`CONSUMER`) buyers are onboarded through the prospect / Click2Comply flow rather than through this API, but they are read here on the same operations and carry the same `BuyerResponse`. - name: KYC description: KYC documents, VIES checks, Mode B verification, profile. - name: Self-service invitations description: | Orchestrate buyer-facing self-service links for KYC submission and prospect onboarding. - name: Orders description: | Register vehicle transactions. Orders may contain one or more VINs; single-VIN is the default. - name: Invoice description: >- Buyer's VAT security deposit invoice (PRELIMINARY) or final invoice (FINAL). - name: Payment description: Proof-of-payment data and documents; pickup readiness trigger. - name: Transport description: Pickup + delivery milestones and documents (CMR, declarations). - name: Compliance description: End-to-end compliance rollup per order. - name: Prospects description: | The seller's Click2Comply campaign links (prospect invitations), and the seller's prospects from every entry channel: the company link, a contact's personal link or a campaign link. - name: Documents description: Typed document download. - name: Webhooks description: Webhook endpoint registration, delivery history, test-fire. paths: /partners/{sellerId}/buyers: parameters: - $ref: '#/components/parameters/SellerIdPath' get: tags: - Buyers summary: Lookup buyer by VAT number or company number. description: | Resolves exactly one buyer of this seller. Supply **exactly one** of `vat` or `companyNumber`; neither and both are both `400`. `companyNumber` is the Novatrade24 partner number, which every buyer has. `vat` matches on the buyer's VAT number alone, so a buyer for whom the platform holds none — a natural person, or a company that never supplied one — is reachable by `companyNumber` only. Which key resolved a buyer says nothing about what kind of party it is: read `type` on the response. Either value is matched exactly, ignoring case and surrounding whitespace. There is no partial or fuzzy matching: a prefix of a real number is a miss, not a hit. A value of the wrong shape is a miss too, not a validation error. A VAT number is not unique, so it can reach both a buyer you recorded yourself and one you reach through another partner's shared KYC result. Where it reaches both, this answers with **your own** record — the one your orders point at and the one a `PATCH` from you should correct. The shared record stays reachable by `companyNumber` and by its `uuid`. operationId: lookupBuyerByVat parameters: - name: vat in: query required: false schema: type: string example: DE123456789 - name: companyNumber in: query required: false schema: type: string example: NT-4K7M-9XQ2 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/BuyerResponse' '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' 4XX: $ref: '#/components/responses/Problem' 5XX: $ref: '#/components/responses/Problem' components: parameters: SellerIdPath: name: sellerId in: path required: true description: UUID of the seller trade partner (must be in caller's authorized list). schema: type: string format: uuid schemas: BuyerResponse: type: object required: - uuid - companyNumber - type - companyName - address - kycMode - status - version - createdAt - updatedAt properties: uuid: type: string format: uuid companyNumber: type: string pattern: ^NT-[A-Z0-9]{4}-[A-Z0-9]{4}$ example: NT-4K7M-9XQ2 description: | The Novatrade24-issued partner number. Every partner has one, whatever its `type`, which is why this — and not `vatNumber` — is the identifier that resolves any buyer. type: $ref: '#/components/schemas/PartyType' vatNumber: type: string description: | The buyer's VAT number, present only when the platform holds one. Its presence does not classify the buyer: no onboarding path gives a natural person a VAT number and a company may never have supplied one, but neither is a guarantee this API makes. Read `type` for the kind of party. companyName: type: string description: | The legal company name for a `COMPANY` buyer, the natural person's full name for a `CONSUMER` buyer. address: $ref: '#/components/schemas/Address' kycMode: $ref: '#/components/schemas/KycMode' status: $ref: '#/components/schemas/BuyerStatus' inactiveSince: type: - string - 'null' format: date-time description: > When the buyer closed its account on Novatrade24 and became inactive; null while it is active. An inactive buyer takes no new order, KYC request or invitation (409), and its existing orders are read-only. version: type: integer description: Optimistic-concurrency version. createdAt: type: string format: date-time updatedAt: type: string format: date-time notApplied: type: array items: type: string example: companyName description: | Fields of an upsert body that named something other than what this record says, and were therefore not written. Two groups, in one list: * the buyer's own fields — `companyName`, `address.street`, `address.postCode`, `address.city`, `address.country`; * a `contacts` entry that disagreed with the person already recorded under its email address — `contacts[0].firstName`, `contacts[0].lastName`, `contacts[0].phone`, where the index is the entry's position in the array you sent — or that asked for a `role` the person did not get, `contacts[0].role`. Present on `POST /buyers` only, and only when there was something to report. Absent on every read and on a call that agreed with the record. Absent on a `201` for the buyer's own fields — a buyer this call just created cannot disagree with the body that created it — but a `contacts` entry can still be reported on a `201`, because an array naming two different people on one email address contradicts itself whatever the buyer's age. Change a buyer field with `PATCH` under `If-Match`. A contact person cannot be changed through this API at all; ask Novatrade24 support. `notApplied` describes your request, not the resource, so it is not part of the buyer's `ETag` and two callers reading the same buyer still see the same tag. PartyType: type: string enum: - COMPANY - CONSUMER description: | Whether the party is a legal entity or a natural person. Shared by `BuyerResponse` and `ProspectResponse`, which describe the same two kinds of party at different points of the onboarding flow. The webhook contract publishes these same two values as `ProspectType` in `asyncapi-integration-v1.yaml`. Two names, one set of values. Address: type: object properties: uuid: type: string format: uuid readOnly: true street: type: string postCode: type: string city: type: string country: type: string description: ISO 3166-1 alpha-2 country code. example: DE KycMode: type: string enum: - MARKETPLACE_LED - NT24_LED description: > `MARKETPLACE_LED` (Mode A), partner provides KYC data; NT24 stores + runs VIES only. Not available yet: a buyer write naming it is refused with `403`. `NT24_LED` (Mode B), NT24 runs full verification (iDenfy + AML) and generates a profile. BuyerStatus: type: string enum: - ACTIVE - BLOCKED Problem: type: object required: - type - title - status properties: type: type: string format: uri title: type: string status: type: integer detail: type: string instance: type: string traceId: type: string responses: BadRequest: description: Malformed request. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Forbidden: description: > Authenticated but not authorized (wrong partner scope, missing capability, or DPA not accepted). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' NotFound: description: Resource not found. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Problem: description: | RFC 9457 problem detail. Default fallback for any status not explicitly enumerated on the operation. Concrete status is in `status` field. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: oauth2ClientCredentials: type: oauth2 description: | OAuth 2.0 client_credentials grant via Keycloak service account. Clients are provisioned per `IntegrationOrganization` in the `nt24-idp` realm. flows: clientCredentials: tokenUrl: >- https://auth.novatrade24.com/realms/nt24-idp/protocol/openid-connect/token scopes: {} ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.