Returns the current KYB (Know Your Business) status and core profile for a single business customer that belongs to the authenticated client. Look up the business by its business_id; the record is always scoped to the caller's own client, so businesses owned by other clients are never returned. This is a read-only endpoint with no side effects.

Authentication & access

• Requires a Bearer token in the Authorization header.
• Permission: kyb.businesses.read.
• Allowed account roles: OWNER, DEVELOPER, OPERATIONS.

Path parameters

• business_id (string, required) - identifier of the business customer to look up. The business must belong to the authenticated client.

Response

200 OK returns a BusinessCustomerKYBStatusResponse describing the business and its verification state. Fields:

• id, company_name, registration_number, country - always present.
• legal_address, tax_id, contact_email - present when known, otherwise null.
• kyb_status - one of none, pending, approved, rejected, on_hold.
• verification_mode - how the business is verified: urbanpayx_kyb (UrbanpayX-managed verification) or external_attestation (the client attests the verification result).
• kyb_level - selected KYB level key (see GET /api/v1/kyb/levels), or null.
• external_verification_status - one of pending, verified, rejected. Used when the business is in external-attestation mode.
• verification_source - origin of the current verification state: none, urbanpayx, or external.
• external_verification_provider, external_verification_ref, external_verified_at - external-attestation metadata, null when not applicable.
• is_active - whether the business customer is active (defaults to true).
• created_at - when the business customer was created.
• latest_kyb_verification_url, latest_kyb_verification_url_generated_at, latest_kyb_verification_url_expires_at - the most recently generated hosted verification link and its timestamps, null when none has been generated.

Error responses

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