Create Business Customer

Time	Status	User Agent
Retrieving recent requests…

Create a business customer record under your client for KYB. This endpoint only provisions the record and resolves its verification configuration; it does not start verification (use POST /api/v1/kyb/verify for that). It is idempotent on (registration_number, country): if a matching business already exists it is returned unchanged. The response reports the created (or existing) business along with its resolved verification mode, KYB level, and status.

Authentication & access

Requires a client API token: Authorization: Bearer <token>.
The caller must hold the kyb.businesses.write permission and have the OWNER or OPERATIONS role.

Request body

Field	Type	Required	Notes
`company_name`	string	yes	1-255 characters.
`registration_number`	string	yes	1-128 characters. Part of the idempotency key.
`country`	string	yes	ISO 3166-1 alpha-3 (exactly 3 characters). Normalized to uppercase. Part of the idempotency key.
`legal_address`	string	no	Up to 512 characters.
`tax_id`	string	no	Up to 128 characters.
`contact_email`	string	no	Valid email address.
`verification_mode`	string	no	`urbanpayx_kyb` or `external_attestation`. Falls back to the client default when omitted.
`kyb_level`	string	no	KYB level key from `GET /api/v1/kyb/levels`. Lowercase alphanumerics, dashes, or underscores; max 64 characters.

Idempotency

A business is keyed on (registration_number, country) within your client. If a business with the same pair already exists:

It is returned unchanged (message is "Business already exists"), with no fields overwritten.
If you send a verification_mode that differs from the existing record's mode, the request is rejected with 409. To change the mode of an existing business, use PATCH /api/v1/kyb/businesses/{business_id}/verification-mode.
kyb_level is immutable for an existing record and is ignored on a repeat call.

Verification mode & KYB level

The effective verification mode is resolved in this order: the request verification_mode, then the client's default business verification mode, then urbanpayx_kyb.

UrbanpayX-managed KYB (urbanpayx_kyb): UrbanpayX runs the verification. The kyb_level you provide must be a currently active key in the level catalog (GET /api/v1/kyb/levels); if omitted, the catalog default is used.
External attestation (external_attestation): you attest the business's verification status yourself. kyb_level does not apply and is stored as null.

Response

200 OK with the business record:

id — the business customer id.
company_name, registration_number, country, contact_email — the stored details.
kyb_status — KYB lifecycle status; none for a freshly created business (no verification started yet). One of none, pending, approved, rejected, on_hold.
verification_mode — the resolved mode (urbanpayx_kyb or external_attestation).
kyb_level — the resolved level key under UrbanpayX-managed KYB, or null for external attestation.
external_verification_status — pending, verified, or rejected. pending for a new record.
verification_source — none, urbanpayx, or external. none for a new record.
created_at — creation timestamp.
message — "Business created successfully" on creation, or "Business already exists" when an existing record was returned.

Error responses

Status	When
`400`	The effective verification mode resolved to a mode that is not valid for business customers (only reachable when the client's configured default is not a business mode).
`409`	A business with the same `registration_number` and `country` already exists with a different `verification_mode` than the one supplied.
`422`	Request body failed validation (e.g. missing required field, wrong `country` length, malformed `kyb_level` format, or a `kyb_level` key not present in the active catalog under `urbanpayx_kyb`).
`500`	A concurrent create raced and the record could not be resolved; retry.

Standard 401 (authentication), 403 (insufficient permission or role), and 429 (rate limit) responses apply to every endpoint and are documented in the Error reference.