Manage customers
Use the following guide to view and track the customers you have created, including their current onboarding and verification status, and to manage their associates, documents, and agreements after onboarding.
The endpoints on this page complement the Create business customers flow. Use them to discover customers on your account, retrieve supporting data, and maintain an application after it has been submitted.
All endpoints on this page operate on platform/v2 resources and return UUIDs in the id field. If you only have a partner-supplied reference, use the customers list endpoint with the reference filter to resolve it to a customer id before calling the other endpoints.
Get customers list
To see all customers on your account, send the GET platform/v2/customers request. The endpoint supports filtering by name, lifecycle status, type, model, and your partner-supplied reference, and returns a paginated list.
In the response, you receive a paginated list of customer summaries. Use the returned id to call GET platform/v2/customers/{id} and retrieve detailed information on a specific customer, or to call any of the other endpoints on this page.
{
"content": [
{
"id": "0a184641-30e2-4414-871f-3db1c683900e",
"reference": "partner-ref-001",
"status": "VERIFIED",
"type": "COMPANY",
"model": "EMBEDDED_BVNK_MANAGED",
"name": "Krause Fintech GmbH",
"createdAt": "2026-04-22T10:57:35.056865Z",
"authenticatedLink": {
"link": "https://onboarding.bvnk.com/link/eyJhbGciOi...",
"expiresAt": "2026-04-22T11:57:35.056865Z"
}
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 20
},
"totalElements": 1,
"totalPages": 1,
"hasNext": false
}
Persist the returned id alongside your own reference in your system. The id is the stable identifier used across every v2 endpoint. The reference is partner-supplied and useful for idempotent lookups from your side.
Manage associates
After creation, you can add, list, retrieve, and remove associates: directors, UBOs, signatories, and registered-business owners while the onboarding has not yet reached a terminal state.
VERIFIED status.Add an associate
To add an associate to an existing customer, send the POST platform/v2/customers/{customerId}/associates request. Use this endpoint when corporate structure changes during onboarding (for example, a new director joins or you need to register an indirect corporate UBO).
The request body is discriminated by entity.type:
PERSON- a natural person such as a UBO, director, signatory, or account representative.BUSINESS_REGISTRATION- a registered-business owner holding shares in the customer.
- Person associate
- Business-registration associate
{
"types": ["UBO", "DIRECTOR"],
"entity": {
"type": "PERSON",
"firstName": "Freya",
"lastName": "Krause",
"email": "freya.krause@krause-fintech.de",
"phoneNumber": "+4915112345678",
"dateOfBirth": "1982-03-24",
"nationality": "DE",
"birthCountryCode": "DE",
"taxIdentificationNumber": "21/815/08150",
"taxResidence": "DE",
"position": "Geschaeftsfuehrer",
"isPoliticallyExposedPerson": false,
"percentageOfOwnership": "100",
"ownershipType": "DIRECT",
"controlOptions": {
"canAppointDirectors": true,
"hasSignificantControl": true,
"controlsManagement": true,
"controlsCorporateBody": true
},
"address": {
"addressLine1": "Heidestrasse 19",
"city": "Koeln",
"postalCode": "51247",
"countryCode": "DE"
}
}
}
In the response, you receive the new associate's id. Use this id to upload identification documents and submit questionnaires for the associate.
{
"id": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240"
}
Remember to send an Idempotency-Key header to safely retry failed requests without creating duplicate associates.
List associates
To list every associate attached to a customer, send the GET platform/v2/customers/{customerId}/associates request.
Use the returned list to reconcile the associates you created locally with what BVNK currently tracks for the customer and to fetch each associate's validation status.
{
"content": [
{
"id": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240",
"types": ["UBO", "DIRECTOR"],
"displayName": "Freya Krause",
"validation": {
"status": "COMPLETE",
"issues": []
},
"createdAt": "2026-04-22T10:57:35.056865Z",
"updatedAt": "2026-04-22T10:57:35.056865Z"
},
{
"id": "3e8a1b4d-2c7f-4f1a-9d3e-5b2a1f6c9d20",
"types": ["UBO"],
"displayName": "Krause Holdings Ltd",
"validation": {
"status": "INCOMPLETE",
"issues": [
{
"field": "entity.registrationNumber",
"message": "Registration number is required."
}
]
},
"createdAt": "2026-04-22T11:02:14.056865Z",
"updatedAt": "2026-04-22T11:02:14.056865Z"
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 20
},
"totalElements": 2,
"totalPages": 1,
"hasNext": false
}
The list response returns only a compact summary for each associate (displayName, validation). To retrieve the full entity body (including identification documents, address, and control options), call GET /platform/v2/customers/{customerId}/associates/{associateId}.
Get an associate
To inspect a single associate, including the documents they have uploaded and any validation errors, send the GET platform/v2/customers/{customerId}/associates/{associateId} request.
{
"id": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240",
"types": ["UBO", "DIRECTOR"],
"entity": {
"type": "PERSON",
"firstName": "Freya",
"lastName": "Krause",
"email": "freya.krause@krause-fintech.de",
"phoneNumber": "+4915112345678",
"dateOfBirth": "1982-03-24",
"nationality": "DE",
"birthCountryCode": "DE",
"taxIdentificationNumber": "21/815/08150",
"taxResidence": "DE",
"position": "Geschaeftsfuehrer",
"isPoliticallyExposedPerson": false,
"percentageOfOwnership": "100",
"ownershipType": "DIRECT",
"controlOptions": {
"canAppointDirectors": true,
"hasSignificantControl": true,
"controlsManagement": true,
"controlsCorporateBody": true
},
"address": {
"addressLine1": "Heidestrasse 19",
"city": "Koeln",
"postalCode": "51247",
"countryCode": "DE"
},
"identificationDocuments": [
{
"type": "PASSPORT",
"country": "DE",
"documentNumber": "C01X00T47",
"issuedDate": "2021-01-15",
"validUntil": "2031-01-14"
}
],
"identityVerification": {
"link": "https://idv.bvnk.com/session/eyJhbGciOi...",
"status": "COMPLETE"
}
},
"validation": {
"status": "COMPLETE",
"issues": []
},
"createdAt": "2026-04-22T10:57:35.056865Z",
"updatedAt": "2026-04-22T11:10:02.056865Z"
}
Delete an associate
To remove an associate from an in-progress onboarding application, send the DELETE platform/v2/customers/{customerId}/associates/{associateId} request.
This endpoint is only safe to call before the application transitions to a terminal state (for example, VERIFIED, REJECTED, or TERMINATED). Attempting to delete an associate from a finalised application will fail.
A successful deletion returns 204 No Content. The associate's uploaded documents are invalidated and must be re-uploaded against a new associate if the person needs to be re-added later.
Manage customer documents
After you upload company documents during onboarding, use the endpoints below to review and download them, for example when reconciling compliance artefacts or responding to an audit.
List customer documents
To retrieve every company-level document uploaded for a customer, send the GET platform/v2/customers/{customerId}/documents request. The endpoint returns a paginated list with document metadata (type, filename, status, timestamps).
Use this endpoint to:
- Confirm that every required document is present before relying on the onboarding completion webhook.
- Surface upload history in your own admin UI.
- Identify documents that failed processing (
status: ERROR) so you can resubmit corrected files viaPOST platform/v2/customers/{customerId}/documents.
Get a specific document
To retrieve metadata for a single document, send the GET platform/v2/customers/{customerId}/documents/{documentId} request.
{
"id": "b8f8a6b5-8f44-4b7c-8d1e-4a6a5a9b4a21",
"filename": "certificate.pdf",
"type": "CERTIFICATE_OF_INCORPORATION",
"checksum": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"status": "COMPLETE",
"createdAt": "2026-04-22T10:58:35.056865Z",
"updatedAt": "2026-04-22T10:58:35.056865Z"
}
Download a document
To download the binary content of a document, send the GET platform/v2/customers/{customerId}/documents/{documentId}/content request. The response is an application/octet-stream file attachment.
Store the documentId returned during upload so you can later re-download the exact artefact that BVNK holds on record. This is typically required when satisfying external audits or responding to EDD questionnaires from downstream partners.
Manage agreements
BVNK provides the agreements your customers must sign and assigns them to each customer automatically during onboarding based on the customer's jurisdiction and account structure (for example, a US or Non-US Partner Platform Agreement). You do not author or upload these agreements yourself: BVNK hosts the canonical text, tracks version changes, and ensures the correct variant is served to each customer.
Use the following endpoints to enumerate, inspect, and retrieve the signed copies of the agreements BVNK has assigned.
List customer agreements
To list every agreement assigned to a customer, send the GET platform/v2/customers/{customerId}/agreements request. The endpoint returns paginated results (maximum page size: 500).
All returned agreements must reach ACCEPTED status before onboarding can complete. Use this endpoint to confirm which agreements are still PENDING and drive your UX to prompt the customer to accept them.
{
"id": "06d119bc-64f6-46b2-aea2-3ff94c4c616f",
"agreement": {
"version": "1.0",
"title": "Partner Platform Agreement (Non-US)",
"locale": "en-GB"
},
"status": "PENDING",
"createdAt": "2026-03-25T10:57:38.145505Z",
"updatedAt": "2026-03-25T10:57:38.145505Z"
}
To accept agreements, use the POST platform/v2/customers/{customerId}/agreements/{assignedAgreementId}/actions or bulk endpoints described in the Create business customers guide.
Download an agreement
To get a short-TTL presigned URL for the agreement PDF, send the GET platform/v2/customers/{customerId}/agreements/{assignedAgreementId}/content request.
In the response, you receive a download URL that expires at the expiresAt timestamp, along with the original filename.
{
"downloadUrl": "https://files.bvnk.com/agreements/c83a528b-8c7a-4d95-9fbb-3fbe14332f7b.pdf?token=...",
"expiresAt": "2026-04-22T11:05:35.056865Z",
"filename": "partner-platform-agreement.pdf"
}
Download links expire one minute after they are issued. Always generate a new link when you need to share the agreement with a customer instead of caching and reusing one from your database.
Use this endpoint to surface the exact agreement text to the customer before they accept it, or to archive a copy of the signed terms in your own document store.