Accounts

Account onboarding is a staged process. Create the local account first, select the account with the AccountId header, then follow the status returned by GetAccountStatusQueryV1.

GetAccountStatusQueryV1 is the source of truth for the next onboarding action. Poll it after account creation and after every user action.

After CreateAccountCommandV1 returns an account id, send AccountId: <uuid> on every account-scoped request. Do not put an account id in the body unless the endpoint contract explicitly asks for one.

Create the account

POST /accounts CreateAccountCommandV1

curl https://api-preview.bridflow.com/accounts   --request POST   --header 'Content-Type: application/json'   --header 'Authorization: Basic <BASE64(uuid:password)>'   --data '{
    "accountType": "Personal",
    "email": "[email protected]"
  }'

Expected response:

{
	"accountId": "123e4567-e89b-12d3-a456-426614174000"
}

Use accountType: "Business" for a business account. An identity may own more than one account. When the identity is already known, the service can reuse its verified person and Sumsub KYC result instead of asking the same person to verify again.

Creation behavior

Omit identityUserId to create the account for the current identity. Only callers with explicit access should create an account for another identity.
A personal identity can have one personal account. Attempting to create a second one returns a validation error.
An unfinished initial account may be reused, so a repeated call can return the existing accountId.
In collaborator context, the command creates a collaborator customer account from the supplied email.

Save the account type

Use this endpoint when the account was created before the user selected its type.

PUT /accounts/type UpdateAccountTypeCommandV1

{
	"accountType": "Personal"
}

Save personal information

Personal information always belongs to the physical person who controls the account. For a business account, this is the administrator opening the account, not the company.

PUT /people/personal-information/v1 UpdatePersonPersonalInformationCommandV1

{
	"birthDate": "1990-01-15",
	"name": "Alex",
	"lastName": "Rivera",
	"address": {
		"streetLine1": "Example Street 10",
		"streetLine2": null,
		"city": "Madrid",
		"stateName": "Madrid",
		"stateCode": "MD",
		"countryName": "Spain",
		"countryCode": "ESP",
		"postalCode": "28001"
	}
}

Country codes use ISO 3166-1 alpha-3 values. Keep the person’s legal name aligned with the identity document. If isPersonalNameCorrectionRequired is true, return the user to this step before starting KYC again.

Get account status

QUERY /accounts/status/v1 GetAccountStatusQueryV1

curl https://api-preview.bridflow.com/accounts/status/v1   --request QUERY   --header 'Content-Type: application/json'   --header 'Authorization: Basic <BASE64(uuid:password)>'   --header 'AccountId: 123e4567-e89b-12d3-a456-426614174000'   --data '{}'

Important response fields:

accountCreationStatus: the next onboarding screen or action.
bridgeAccountStatus: the provider-side account state.
bridgeAccountCreationSubmittedAt: when the provider submission started. Use this timestamp instead of restarting a waiting timer after a page reload.
existingAccountSignInRequired: the person already has an account under another sign-in. Do not reveal its email or other account data.
isPersonalNameCorrectionRequired: the legal name must be corrected before verification can continue.
isAdditionalInformationRequired: the provider needs more information.
isProofOfAddressRequired and isProofOfAddressRejected: whether a new proof of address is needed.
proofOfAddressRequiredFullName and proofOfAddressRequiredAddressLines: the exact name and address the document must show.
wallets: app wallets available after account creation.
rejectionReasons: safe reasons that can be shown or mapped to a user action.

Personal onboarding lifecycle

Status	Integration action
`CreateAccount`	Create the local account and select it with the returned `accountId`.
`SelectAccountType`	Save `Personal` or `Business` with `UpdateAccountTypeCommandV1`.
`FillPersonalInformation`	Collect and save the physical person’s legal name, birth date, and residential address.
`SumsubKnowYourCustomer`	Open the returned Sumsub verification session.
`SumsubWaitForKnowYourCustomer`	Wait for the identity review. Do not create a second applicant or ask for a duplicate submission.
`BridgeAcceptTermsOfService`	Generate and present the terms link, then record the signed agreement.
`BridgeFillRegulatoryInformation`	Collect and submit the required regulatory answers.
`BridgeProvideSourceOfFundsData`	Collect the requested source-of-funds information.
`UploadProofOfAddress`	Upload a new document and poll status with the returned file id.
`BridgeWaitingForCreatingAccount`	The submission is processing or under manual review. Keep polling; do not submit a new customer.
`BusinessOnboarding` and `BusinessOnboarding*`	Continue the staged business onboarding.
`Complete`	The account can use wallets, saved contacts, transfers, and Auto Convert Routes.
`ProblemAccountDeactivated`	Stop onboarding and show a safe support message. Do not retry account creation automatically.

Do not use provider-hosted KYC as the normal onboarding path. Identity verification is handled through the Sumsub session returned by the account status response, and business data is collected through the business onboarding endpoints.

Accept terms of service

Create the terms link

POST /integrations/bridge/customers/tos-link/v1 GetBridgeTermsOfServiceLinkCommandV1

Open the returned link for the user. Keep the signed agreement id from the completed flow.

Record acceptance

POST /integrations/bridge/customers/tos-acceptance/v1 AcceptBridgeTermsOfServiceCommandV1

{
	"signedAgreementId": "signed-agreement-id"
}

Poll account status again after acceptance.

Upload proof of address

POST /accounts/kyc/proof-of-address/v1 UploadProofOfAddressCommandV1

curl https://api-preview.bridflow.com/accounts/kyc/proof-of-address/v1   --request POST   --header 'Authorization: Basic <BASE64(uuid:password)>'   --header 'AccountId: 123e4567-e89b-12d3-a456-426614174000'   --form '[email protected]'

The response contains proofOfAddressStaticFileId. Pass it in the next status query:

{
	"proofOfAddressStaticFileId": "123e4567-e89b-12d3-a456-426614174001"
}

Show the required full name and address from the status response before upload. The document should be recent, readable, and match those values. A client-side limit of 22 MB is recommended so the upload remains below the provider limit.

Waiting and manual review

When bridgeAccountStatus is UnderReview, the provider is reviewing the account. Use bridgeAccountCreationSubmittedAt to decide whether to show a short processing message or a longer manual-review message. The user may leave the page while the integration keeps polling.

If a create or submit call times out, the result may be unknown. Keep the account in its waiting state and retry only with the same idempotency context. Never create a second provider customer to work around a timeout.