Onboarding
Complete KYC or KYB over the API, from the profile and documents to terms, submission and review, and know what each state lets you call.
Before an account can move money, it passes due diligence: a profile, the documents that prove it, the terms it accepts, and a review. The same routes serve the Customer panel's onboarding screens and your own system.
Who calls these routes
Your own company completes its onboarding in the Customer panel: API keys can be created only once an account is active. A Platform uses these routes to onboard its End Customers from its own system, with the Apex-End-Customer header. The examples below do that; without the header, the same calls act on your own account.
States
state | standing | What is happening |
|---|---|---|
profile_pending | onboarding | You fill in the profile, upload documents and accept the terms. |
profile_review | onboarding | Submitted. Our compliance team reviews it. Profile, documents and terms are locked. |
contract_pending | onboarding | Approved, waiting for our own terms to be accepted. Direct Customers only. |
provider_onboarding | onboarding | The application is with the Providers. The account opens on the first approval. |
active | active | Open: every route is available. |
suspended | suspended | Read-only. |
rejected | closed | The application was refused. |
An End Customer has no contract_pending step: its path is profile_pending, profile_review, provider_onboarding, active.
What each standing lets you call
standing | Available | Everything else |
|---|---|---|
onboarding | GET /v1/customer, GET /v1/onboarding, GET and PUT /v1/profile, POST /v1/profile/submit, GET and POST /v1/terms, /v1/documents | customer_not_active (403), reads included. Balances, Beneficiaries, quotes and Payouts wait until the account is active. |
active | Every route your key's permissions allow. | |
suspended | Every read. | Writes answer customer_suspended (403). |
closed | Nothing. | customer_not_active (403) on every request. |
Within onboarding, the profile, documents and terms can be changed only in profile_pending. In any later state those writes answer profile_locked (409).
Permissions
| Route | Permission |
|---|---|
GET /v1/onboarding, GET /v1/terms | customer:read |
GET and PUT /v1/profile, POST /v1/profile/submit, POST /v1/terms, every /v1/documents route | customer:profile:write |
Read where you stand
GET /v1/onboarding answers everything a next step depends on, in one call.
curl "$APEX_BASE_URL/v1/onboarding" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Apex-End-Customer: $END_CUSTOMER_ID"{
"type": "business",
"state": "profile_pending",
"standing": "onboarding",
"requested_fields": [],
"missing_fields": [
{ "field": "business.registration_number", "message": "required" },
{ "field": "business.corridors", "message": "at least one corridor" }
],
"documents": [
{ "kind": "certificate_of_incorporation", "subject_kind": "business", "uploaded": false },
{ "kind": "proof_of_address", "subject_kind": "business", "uploaded": true },
{ "kind": "government_id", "subject_kind": "ubo", "subject_ref": "Ada Brooks", "uploaded": false }
],
"terms_accepted": false,
"providers": []
}| Field | Meaning |
|---|---|
state, standing | See States. |
note | What our compliance team wrote when it sent the profile back, word for word. Absent otherwise. |
requested_fields | The fields compliance asked you to look at again. |
missing_fields | What the saved profile still lacks, by field path. Empty when it is complete. |
documents | The documents a submission needs, each with uploaded. |
terms_accepted | Whether every set of terms in force is accepted. |
providers | The application at each Provider: submitted, info_required, approved, rejected or terminated. |
You can submit when missing_fields is empty, every document is uploaded, and terms_accepted is true.
Save the profile
PUT /v1/profile saves a draft. A draft may be incomplete: save as often as you like while the state is profile_pending. Only the side of the account's type is kept, business or individual. GET /v1/profile answers the draft or the last submission.
curl -X PUT "$APEX_BASE_URL/v1/profile" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Apex-End-Customer: $END_CUSTOMER_ID" \
-H "Content-Type: application/json" \
-d '{
"data": {
"business": {
"legal_name": "Harbor Crafts LLC",
"registration_number": "7734120",
"address": {
"line1": "100 Pier Avenue",
"city": "Wilmington",
"region": "DE",
"postal_code": "19801",
"country": "US"
},
"entity_type": "llc",
"ubos": [
{ "name": "Ada Brooks", "country": "US", "share_percent": "60" }
],
"authorised_persons": [
{ "name": "Ada Brooks", "email": "ada@harborcrafts.example.com", "role": "CEO" }
],
"expected_monthly_volume": { "amount": "50000", "asset": "USDC" },
"corridors": ["US:USDC>DE:EUR"]
}
}
}'Business profile
| Field | Required at submission | Notes |
|---|---|---|
legal_name | Yes | |
registration_number | Yes | |
address | Yes | line1, city and country are required; line2, region and postal_code are optional. region is the subdivision part of an ISO 3166-2 code, such as DE or CA. |
ubos | At least one | Each ultimate beneficial owner: name, country, share_percent; optionally date_of_birth, nationality, address. |
authorised_persons | At least one | Each person who acts for the company: name, email, optionally role. |
expected_monthly_volume | Yes | A positive amount in an asset, such as { "amount": "50000", "asset": "USDC" }. |
corridors | At least one | The corridors you plan to use, such as US:USDC>DE:EUR. |
tax_id, phone, website, date_established, entity_type | No | phone in international form (+13125550100), website as an https URL, dates as YYYY-MM-DD, entity_type one of corporation, llc, partnership, sole_proprietorship, trust, other. A Provider may need them. |
control_persons | No | People who control the company: name, optionally title, date_of_birth, nationality, tax_id, address. |
The company's address.country must be the account's own country.
Individual profile
| Field | Required at submission |
|---|---|
full_name | Yes |
date_of_birth | Yes, as YYYY-MM-DD |
nationality | Yes, a two-letter country code |
address | Yes, as for a business; its country must be the account's own country |
Upload documents
POST /v1/documents takes a multipart/form-data body:
| Part | Meaning |
|---|---|
file | The file: PDF, JPEG or PNG, judged from its content, at most 10 MB. |
kind | certificate_of_incorporation, articles_or_by_laws, certificate_of_good_standing, operating_agreement, proof_of_address, ownership_structure, government_id or other. |
subject_kind | Whom it is about: business, ubo, control_person or individual. |
subject_ref | For ubo and control_person only: the person's name, exactly as in the profile. |
A submission needs:
| Account | Documents |
|---|---|
| Business | certificate_of_incorporation and proof_of_address about the business, and a government_id for every UBO and every control person. |
| Individual | government_id and proof_of_address about the individual. |
Other kinds are welcome when they help the review, and a Provider may ask for them.
curl -X POST "$APEX_BASE_URL/v1/documents" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Apex-End-Customer: $END_CUSTOMER_ID" \
-F "file=@ada-brooks-passport.pdf" \
-F "kind=government_id" \
-F "subject_kind=ubo" \
-F "subject_ref=Ada Brooks"{
"id": "5e8a1c3b-7d9f-4b2e-a6c4-0f1e2d3c4b5a",
"kind": "government_id",
"subject_kind": "ubo",
"subject_ref": "Ada Brooks",
"file_name": "ada-brooks-passport.pdf",
"mime": "application/pdf",
"size_bytes": 482113,
"sha256": "4c1f0b7e9a2d38c56e7f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d",
"version": 1,
"current": true,
"uploaded_at": "2026-11-12T09:12:00Z"
}- A new file of the same kind about the same subject becomes the next
version. The earlier one is kept, withcurrentset tofalseand asuperseded_at. Nothing is ever deleted. - The route takes no
Idempotency-Key: an upload sent twice is simply one more version. GET /v1/documentslists every version, newest first.GET /v1/documents/{id}/contentdownloads one file as an attachment.- Uploads are refused with
profile_locked(409) once the profile is submitted.
Accept the terms
GET /v1/terms lists the terms to accept: our own terms for a direct Customer, and the terms of each Provider the account will be sent to. An End Customer accepts only the Providers' terms. Show each url to the person accepting.
{
"version": "provider:bvnk@fake-1|provider:zerohash@fake-1",
"documents": [
{ "id": "provider:bvnk", "provider": "bvnk", "url": "https://example.invalid/terms/bvnk", "version": "fake-1" },
{ "id": "provider:zerohash", "provider": "zerohash", "url": "https://example.invalid/terms/zerohash", "version": "fake-1" }
],
"accepted": false
}Accept by sending the set's version back, exactly as you read it. If the set changed after you read it, the call answers terms_changed (409): read it again and show the new terms.
curl -X POST "$APEX_BASE_URL/v1/terms" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Apex-End-Customer: $END_CUSTOMER_ID" \
-H "Content-Type: application/json" \
-d '{ "version": "provider:bvnk@fake-1|provider:zerohash@fake-1" }'Each acceptance is recorded with who accepted and when; the answer carries accepted_at on each document. Terms can be accepted in profile_pending, before submission, or in contract_pending.
Submit
POST /v1/profile/submit sends everything to review and answers the same view as GET /v1/onboarding, now in profile_review.
curl -X POST "$APEX_BASE_URL/v1/profile/submit" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Apex-End-Customer: $END_CUSTOMER_ID"If anything is missing, the call answers profile_invalid (422) and names every field and document in details:
{
"code": "profile_invalid",
"message": "the Compliance Profile is incomplete",
"correlation_id": "c0a8012e-6b1f-4d2a-9e3c-7f5a4b3c2d1e",
"details": [
{ "field": "business.registration_number", "message": "required" },
{ "field": "documents.ubo.Ada Brooks.government_id", "message": "required" }
]
}| Code | Status | Cause |
|---|---|---|
profile_invalid | 422 | Fields or documents are missing or malformed; see details. |
profile_missing | 422 | Nothing was saved yet. |
terms_not_accepted | 409 | The terms in force are not all accepted. |
country_mismatch | 422 | The address is in another country than the account's. |
country_not_accepted | 422 | We no longer accept Customers from that country. |
profile_locked | 409 | The profile was already submitted. |
Review and Providers
Our compliance team reviews the submission. The outcome shows in GET /v1/onboarding:
| Outcome | What you see | What to do |
|---|---|---|
| Approved | state moves on to provider_onboarding (or contract_pending while our own terms wait). | Nothing. The application goes to the Providers. |
| More information needed | state is back to profile_pending, with note and requested_fields. | Fix what the note asks, upload any new document, then submit again. |
| Refused | state is rejected, standing is closed. | Every request now answers customer_not_active. Contact your account manager. |
In provider_onboarding, providers shows each application's progress. The account becomes active as soon as one Provider approves it, and from then on the money routes open. Payouts can use only routes whose Providers have approved the account; a quote over the others answers onboarding_required.
For an End Customer, read its progress with GET /v1/onboarding under its header or with GET /v1/end-customers/{id}. There is no webhook for onboarding changes.
Document errors
| Code | Status | Cause |
|---|---|---|
document_file_required | 400 | No file part. |
document_empty | 422 | The file is empty. |
document_too_large | 413 | The file is over 10 MB. |
document_type_not_allowed | 422 | The content is not a PDF, JPEG or PNG. |
document_kind_unknown | 422 | Unknown kind. |
document_subject_invalid | 422 | Unknown subject_kind, or subject_ref missing, or given where it does not belong. |
document_limit_reached | 422 | The account holds the most document versions or bytes it may. |
document_not_found | 404 | No document of the account has this id. |
document_busy | 503 | Too many files are being handled right now. Retry shortly. |