Pre-populate KYB

If you already hold information about a corporate from your own onboarding, you can send it to us before KYB starts. Company, ownership, and account-usage details are then already in place when the root user opens the KYB UI Component, so they only need to review them rather than enter them again. Supporting documents you upload go to our compliance team for review.

Pre-population is optional. Each of the following endpoints can be used on its own, in any combination, and every field in them is optional, so send what you have. If you send nothing, the standard KYB flow works as usual.

What you hold	Endpoint
Company details and ownership structure (companies, individuals, and how they relate)	POST`/corporates/{corporateId}/kyb/entity`
How the corporate intends to use its account (funding, volumes, collections, payouts, cards)	POST`/corporates/{corporateId}/kyb/profile`
Supporting documents (registration certificate, shareholder register, and so on)	POST`/corporates/{corporateId}/kyb/documents`

Before you begin

Your corporate profile must be set up for KYB pre-population, and submitting company and ownership data (/kyb/entity) must also be turned on for the profile. We manage both settings, so contact our support team to turn them on. If a profile isn't set up, the endpoint returns NOT_SUPPORTED.

These are server-side calls authenticated with your API key. They identify the corporate by the corporateId path parameter, so no user token is needed. The corporate must belong to your programme.

You can pre-populate any time between creating the corporate and starting KYB, and you can call each endpoint more than once in that window. Each of the following endpoint sections explains what a repeat call does. The root user doesn't need to have verified their email yet. Once KYB has started, every call is rejected with KYB_ALREADY_STARTED.

note

You can't remove data through the API. Repeat calls add or update information but never delete it. If something was sent in error, the root user corrects or removes it in the KYB UI Component after KYB starts.

The end-to-end flow

Create the corporate and keep the returned id.
Pre-populate KYB with any of the entity, profile, and document endpoints, in any order.
Set up the root user, including email verification. This can run in parallel with step 2.
Start KYB. This closes the pre-population window.
Render the KYB UI Component with the returned reference. The root user reviews and, if needed, edits the pre-populated details, completes anything still missing, and submits.
Track the outcome through the corporate KYB webhook or GET /corporates/kyb.

1. Create the corporate

Register the corporate as described in Create a corporate. The response contains the corporate id, which you pass as corporateId in every pre-population call.

The corporate's name, registration number, and registration country are taken from this record. You don't send them again when pre-populating.

2. Submit company and ownership data

POST/corporates/{corporateId}/kyb/entityOpen reference

The request body has four parts:

company - additional details about the corporate itself, such as registration date, legal form, industry classifications, tax identifiers, addresses, and website.
companies - other companies in the ownership structure, such as a parent or holding company.
individuals - people in the structure, with flags such as isBeneficialOwner, isControllingPerson, and isSignatory.
relations - how companies and individuals connect to each other and to the corporate.

Describe the ownership graph

Give each entry in companies and individuals a ref of your own choosing. Then link them in relations: fromRef is the holder of the stake or role, and toRef is the company it's held in. Leave toRef empty to point at the corporate itself. Each relation can carry roles (SHAREHOLDER, LEGAL_REPRESENTATIVE), ownershipPercentage, votingRightsPercentage, and position.

In this example, Alex Smith owns 60% of a holding company, which owns 100% of the corporate:

{
  "companies": [
    {
      "ref": "holding",
      "details": {
        "name": "Acme Holdings Ltd",
        "registrationNumber": "87654321",
        "country": "GB"
      }
    }
  ],
  "individuals": [
    {
      "ref": "alex",
      "details": {
        "firstName": "Alex",
        "lastName": "Smith",
        "email": "[email protected]",
        "birthDate": "1990-01-01"
      },
      "isBeneficialOwner": true,
      "isSignatory": true
    }
  ],
  "relations": [
    {
      "fromRef": "alex",
      "toRef": "holding",
      "roles": ["SHAREHOLDER"],
      "ownershipPercentage": 60
    },
    {
      "fromRef": "holding",
      "roles": ["SHAREHOLDER"],
      "ownershipPercentage": 100
    }
  ]
}

Two rules are checked when you submit:

Every fromRef and toRef must match a ref in this request or in an earlier call for the same corporate, otherwise the call fails with INVALID_REF.
Only the corporate's root user can be marked isSignatory, otherwise the call fails with SIGNATORY_MUST_BE_ROOT. We match the individual to the root user by email, or by first and last name if either email is missing, so include the root user's email in details to make the match unambiguous.

Calling this endpoint more than once

Each call is applied on top of what you sent before. It doesn't replace the earlier submission as a whole. In practice:

Keep each ref stable for the same company or person across calls.
The simplest approach is to send the complete company and ownership data each time.

If a call fails with INVALID_REF, some companies or individuals in it may already have been stored. Fix the relations and send the same call again. Because entries are matched by ref, nothing is duplicated.

3. Submit the account-usage profile

POST/corporates/{corporateId}/kyb/profileOpen reference

This answers the account-usage part of the KYB questionnaire on the corporate's behalf: where funds come from and go to, expected monthly transaction counts and values, and whether collections, payouts, and cards will be used. All fields sit inside a single profile object and are optional.

{
  "profile": {
    "fundingOrigin": "Business revenue",
    "fundingTransactionCountMonthly": "200",
    "fundingTransactionValueMonthly": "50000",
    "cardsEnabled": true,
    "cardsPurpose": "Employee expenses",
    "cardsCardholderCount": "10",
    "payoutsEnabled": false,
    "collectionsEnabled": false
  }
}

See POST/corporates/{corporateId}/kyb/profile for the full list of fields.

Calling this endpoint more than once

Each call updates the profile field by field.

In a later call, you…	What happens
Send a field again with a new value	The new value replaces the earlier one.
Leave out a field, or send it empty	The earlier answer is kept. An answer can't be cleared.
Send exactly the same request again	Nothing changes.

To keep it simple, send the complete profile each time you call.

4. Upload supporting documents

POST/corporates/{corporateId}/kyb/documentsOpen reference

Upload one document per call as multipart/form-data, with these fields:

file (required) - the document, up to 10 MB, as PDF, PNG, JPEG, WebP, or DOCX. Set the part's Content-Type to match the file. The file type is checked against it.
documentType (required) - the type of document.
description (optional) - free text describing the document, up to 500 characters.

For example, where $BASE_URL is the Weavr API base URL for your environment:

curl -X POST "$BASE_URL/corporates/$CORPORATE_ID/kyb/documents" \
  -H "api-key: $API_KEY" \
  -F "[email protected];type=application/pdf" \
  -F "documentType=REGISTRATION_CERTIFICATE" \
  -F "description=Certificate of incorporation"

The response contains a reference for the stored document. Keep it if you want to match documents on your side later.

Our compliance team reviews uploaded documents and adds accepted ones to the corporate's KYB case. They aren't shown to the root user in the KYB UI Component directly.

Calling this endpoint more than once

Every call stores a new document, with its own reference.

In a later call, you…	What happens
Upload another document, of the same or a different type	It's added alongside the earlier ones.
Upload the same file again	A second copy is stored. Duplicates aren't detected.
Want to replace or withdraw a document	Not possible through the API. Upload the correct document. We review everything received.

Upload each document once. If a call times out without a response, you can't tell whether the document was stored. Retrying may store a second copy, which is harmless but adds to review.

Document types

Document types are a fixed list. Use one of the documentType values listed in POST/corporates/{corporateId}/kyb/documents. A missing or unknown value is rejected with a 400.

Document requirements

The API checks only the file's size and type. Whether a document is acceptable - for example, that a proof of address is no older than three months - is decided by our compliance policy and checked during review, not when you upload.

A document that doesn't meet the policy is raised during review, and the root user is asked to provide a replacement (the KYB run moves to RESUBMISSION.IN_PROGRESS).

Check what you've sent

Before starting KYB, you can read back what's been recorded for the corporate:

GET/corporates/{corporateId}/kyb/entity returns the company details and ownership graph, together with the corporate's own name, registration number, and registration country.
GET/corporates/{corporateId}/kyb/profile returns the account-usage profile.
GET/corporates/{corporateId}/kyb/documents lists the uploaded documents. It returns metadata only (reference, documentType, description, and filename), not the files themselves.

5. Start KYB

When you've sent everything you hold, start KYB as described in Start KYB. The root user's email must be verified first, otherwise the call returns EMAIL_UNVERIFIED.

A successful Start KYB closes the pre-population window. From this point the entity, profile, and document endpoints return KYB_ALREADY_STARTED.

Managed onboarding

On managed-onboarding programmes, Start KYB only succeeds once the KYB run reaches COLLECTION.READY_TO_START. Before that it returns MANAGED_ONBOARDING_PENDING. That response doesn't close the window, so you can keep pre-populating while you wait.

6. The root user completes and submits KYB

Initialize the KYB UI Component with the reference returned by Start KYB. When the root user opens it, the KYB run moves to COLLECTION.IN_PROGRESS and the company, ownership, and account-usage details you sent are already filled in. The root user reviews them, edits or removes anything that needs correcting, adds anything missing, and submits, which moves the run to REVIEW.IN_PROGRESS.

Track the outcome

Listen to the corporate KYB webhook or call GET /corporates/kyb. Use corporateKybStatus to decide whether the corporate can use financial services, and the latest entry in kybRuns to follow the verification itself:

KYB run status	What to do
`REVIEW.IN_PROGRESS`	Nothing, we're reviewing. You may want to show a "review in progress" message.
`RESUBMISSION.IN_PROGRESS`	Ask the root user to return to the KYB UI Component and provide what was requested.
`KYB_RUN.APPROVED`	`corporateKybStatus` becomes `APPROVED`. The corporate can use financial services.
`KYB_RUN.REJECTED`	`corporateKybStatus` becomes `REJECTED`.

For the full list of statuses, see Corporate KYB status and KYB runs.

Errors

Error code	Endpoints	Meaning and fix
`KYB_ALREADY_STARTED`	All three	KYB has started, so pre-population is closed. Remaining information is collected through the KYB UI Component.
`NOT_SUPPORTED`	All three	The corporate's profile isn't set up for KYB pre-population. On the entity endpoint it can also mean that submitting company and ownership data isn't turned on for the profile. Contact our support team.
`INVALID_REF`	Entity	A relation names a `ref` that isn't in this request or an earlier one. Check every `fromRef` and `toRef`, then retry with the same refs.
`SIGNATORY_MUST_BE_ROOT`	Entity	`isSignatory` is set on someone who doesn't match the root user. Check the email, or the first and last name.
`DOCUMENT_TOO_LARGE`	Documents	The file is over 10 MB.
`UNSUPPORTED_DOCUMENT_FORMAT`	Documents	The file's `Content-Type` isn't PDF, PNG, JPEG, WebP, or DOCX.
`INVALID_DATA`	All three	We couldn't store the data. Retry, and if it persists, contact our support team.

Requests that fail basic validation - for example a missing or unknown documentType, an empty file, or a description over 500 characters - return 400.

Before you begin​

The end-to-end flow​

1. Create the corporate​

2. Submit company and ownership data​

Describe the ownership graph​

Calling this endpoint more than once​

3. Submit the account-usage profile​

Calling this endpoint more than once​

4. Upload supporting documents​

Calling this endpoint more than once​

Document types​

Document requirements​

Check what you've sent​

5. Start KYB​

6. The root user completes and submits KYB​

Track the outcome​

Errors​

Related​

Before you begin

The end-to-end flow

1. Create the corporate

2. Submit company and ownership data

Describe the ownership graph

Calling this endpoint more than once

3. Submit the account-usage profile

Calling this endpoint more than once

4. Upload supporting documents

Calling this endpoint more than once

Document types

Document requirements

Check what you've sent

5. Start KYB

6. The root user completes and submits KYB

Track the outcome

Errors

Related