Skip to Content
Apex Settlement

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

statestandingWhat is happening
profile_pendingonboardingYou fill in the profile, upload documents and accept the terms.
profile_reviewonboardingSubmitted. Our compliance team reviews it. Profile, documents and terms are locked.
contract_pendingonboardingApproved, waiting for our own terms to be accepted. Direct Customers only.
provider_onboardingonboardingThe application is with the Providers. The account opens on the first approval.
activeactiveOpen: every route is available.
suspendedsuspendedRead-only.
rejectedclosedThe 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

standingAvailableEverything else
onboardingGET /v1/customer, GET /v1/onboarding, GET and PUT /v1/profile, POST /v1/profile/submit, GET and POST /v1/terms, /v1/documentscustomer_not_active (403), reads included. Balances, Beneficiaries, quotes and Payouts wait until the account is active.
activeEvery route your key's permissions allow.
suspendedEvery read.Writes answer customer_suspended (403).
closedNothing.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

RoutePermission
GET /v1/onboarding, GET /v1/termscustomer:read
GET and PUT /v1/profile, POST /v1/profile/submit, POST /v1/terms, every /v1/documents routecustomer: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"
200 OK
{
  "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": []
}
FieldMeaning
state, standingSee States.
noteWhat our compliance team wrote when it sent the profile back, word for word. Absent otherwise.
requested_fieldsThe fields compliance asked you to look at again.
missing_fieldsWhat the saved profile still lacks, by field path. Empty when it is complete.
documentsThe documents a submission needs, each with uploaded.
terms_acceptedWhether every set of terms in force is accepted.
providersThe 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

FieldRequired at submissionNotes
legal_nameYes
registration_numberYes
addressYesline1, 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.
ubosAt least oneEach ultimate beneficial owner: name, country, share_percent; optionally date_of_birth, nationality, address.
authorised_personsAt least oneEach person who acts for the company: name, email, optionally role.
expected_monthly_volumeYesA positive amount in an asset, such as { "amount": "50000", "asset": "USDC" }.
corridorsAt least oneThe corridors you plan to use, such as US:USDC>DE:EUR.
tax_id, phone, website, date_established, entity_typeNophone 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_personsNoPeople 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

FieldRequired at submission
full_nameYes
date_of_birthYes, as YYYY-MM-DD
nationalityYes, a two-letter country code
addressYes, as for a business; its country must be the account's own country

Upload documents

POST /v1/documents takes a multipart/form-data body:

PartMeaning
fileThe file: PDF, JPEG or PNG, judged from its content, at most 10 MB.
kindcertificate_of_incorporation, articles_or_by_laws, certificate_of_good_standing, operating_agreement, proof_of_address, ownership_structure, government_id or other.
subject_kindWhom it is about: business, ubo, control_person or individual.
subject_refFor ubo and control_person only: the person's name, exactly as in the profile.

A submission needs:

AccountDocuments
Businesscertificate_of_incorporation and proof_of_address about the business, and a government_id for every UBO and every control person.
Individualgovernment_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"
201 Created
{
  "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, with current set to false and a superseded_at. Nothing is ever deleted.
  • The route takes no Idempotency-Key: an upload sent twice is simply one more version.
  • GET /v1/documents lists every version, newest first. GET /v1/documents/{id}/content downloads 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.

GET /v1/terms, 200 OK
{
  "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:

422 Unprocessable Entity
{
  "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" }
  ]
}
CodeStatusCause
profile_invalid422Fields or documents are missing or malformed; see details.
profile_missing422Nothing was saved yet.
terms_not_accepted409The terms in force are not all accepted.
country_mismatch422The address is in another country than the account's.
country_not_accepted422We no longer accept Customers from that country.
profile_locked409The profile was already submitted.

Review and Providers

Our compliance team reviews the submission. The outcome shows in GET /v1/onboarding:

OutcomeWhat you seeWhat to do
Approvedstate moves on to provider_onboarding (or contract_pending while our own terms wait).Nothing. The application goes to the Providers.
More information neededstate is back to profile_pending, with note and requested_fields.Fix what the note asks, upload any new document, then submit again.
Refusedstate 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

CodeStatusCause
document_file_required400No file part.
document_empty422The file is empty.
document_too_large413The file is over 10 MB.
document_type_not_allowed422The content is not a PDF, JPEG or PNG.
document_kind_unknown422Unknown kind.
document_subject_invalid422Unknown subject_kind, or subject_ref missing, or given where it does not belong.
document_limit_reached422The account holds the most document versions or bytes it may.
document_not_found404No document of the account has this id.
document_busy503Too many files are being handled right now. Retry shortly.

Next steps

On this page