Onboarding

Before an organization can move money, Ele must verify it. For a business this is KYB (know your business): who the company is, what it does and who is behind it. Each person involved goes through KYC (know your customer), an identity check. This guide shows how to run both from your product.

What you can do

• Create an organization for a client.
• Submit the business’s details, activity and source of funds.
• Run the business and identity checks inside your own front end, using Sumsub’s WebSDK.
• Upload the documents Ele asks for.
• Read what is still missing, and what the organization can do now.

The sequence

1. Create the organization

Call createOrganization. Set registered_entity to true for a registered company. country_code defaults to the signed-in user’s signup country.

This guide covers registered businesses. For a person trading on their own, see Individual organizations below.

curl -s "$ELE_API_BASE/api/v1/organizations" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H "Idempotency-Key: $KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name": "Acme Trading Pte Ltd", "registered_entity": true, "country_code": "SG"}'

The person who creates an organization becomes its owner. Only Ele support can transfer ownership later (see Organizations and roles), so decide who should own each client’s organization before you create it.

A user can own only a few organizations: three, unless Ele has raised the limit. getMe returns the user’s limit as user.organization_limit; compare it with the organizations where their role is owner. Past the limit, createOrganization answers 422 organization_limit_reached. If your staff will create an organization for each client, ask your Ele contact to raise the limit before you start onboarding clients.

The rest of this guide needs an owner or admin of the organization, except where it says otherwise.

2. Read what is required

getOrganizationCapabilities returns the organization’s checklist in requirements, one line per thing Ele needs, alongside what the organization can do (step 7).

curl -s "$ELE_API_BASE/api/v1/organizations/$ORGANIZATION_ID/capabilities" \
  -H "Authorization: Bearer $ELE_TOKEN"

Each line has a key, a label to show, a kind (field, document, attestation or process), and a subject: organization for the company, or owner for the owner’s own details. Its status tells you whose move it is; see States. A line with optional set to true is not needed for sign-up, but another capability, or Ele’s review, may still need it; collect it when you can. A document line lists the kinds of document Ele accepts in accepts.

Only owners and admins get the lines; other members get an empty requirements list. A member can read the document checklist in step 6 instead.

3. Submit the business details

A registered business submits three forms. Several fields take IDs from fixed lists: get them from getBusinessQuestionnaireOptions, which returns company_registration_types, industries, source_of_funds, purposes and monthly_volumes.

curl -s "$ELE_API_BASE/api/v1/onboarding/questionnaire-options/business" \
  -H "Authorization: Bearer $ELE_TOKEN"

Then send each form:

• submitKybBusinessDetails: company name, registration type and number, country of registration, tax ID, registration address, and the operating address if it differs.
• submitKybBusinessActivity: what the business does, its industry, website, and any regulatory licence.
• submitKybRevenueFunds: annual income, source of funds, purpose, expected monthly volume, and whether it handles other people’s money.

curl -s "$ELE_API_BASE/api/v1/organizations/$ORGANIZATION_ID/kyb/business-details" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H "Idempotency-Key: $KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "company_name": "Acme Trading Pte Ltd",
    "company_registration_type_id": "'"$REGISTRATION_TYPE_ID"'",
    "registration_number": "201912345K",
    "country_of_registration": "SG",
    "tax_id": "201912345K",
    "registration_address": {"address_line1": "1 Raffles Place", "city": "Singapore", "country_code": "SG"},
    "is_operating_address_same_as_registration_address": true
  }'

These forms are for registered businesses only. For an organization with registered_entity set to false, Ele refuses them with 403 forbidden. To prefill a form the person left halfway, read back what was submitted with getKybBusinessProfile. It returns null until something has been submitted, and any member can read it.

4. Run the business check in your front end

The business check runs in Sumsub’s WebSDK, a component you embed in your own web page or app. Your server gets a token for it from createKybAccessToken:

curl -s -X POST "$ELE_API_BASE/api/v1/organizations/$ORGANIZATION_ID/kyb/access-token" \
  -H "Authorization: Bearer $ELE_TOKEN"

{ "access_token": "…", "websdk_link": null }

Submit the business details (step 3) first: Ele uses them to set up the check, and refuses the token until they are there.

What to do with the token:

1. Pass access_token to your front end, and start the WebSDK with it.
2. The token is short-lived. The WebSDK asks for a new one when it expires: have it call your server, and have your server call this operation again.
3. Treat the token as a credential. Do not log it or store it.

In the sandbox, websdk_link is a hosted page that runs the same check, useful for testing without a front end. In production it is always null.

Ele ignores an Idempotency-Key on this call, so each call returns a new token (see Idempotency).

5. The signed-in person’s own identity check

The company’s directors and beneficial owners are named during the business check in step 4. They do not need Ele accounts. When Ele needs a document from one of them, it appears on the document checklist under that person, and an owner or admin uploads it (step 6).

A user’s own identity is different: it is checked against their own Ele account. This applies to the organization’s owner, whose identity the organization’s requirements include, and to any user whose own requirements ask for it. getViewerCapabilities lists what the signed-in user still owes for themselves, in requirements lines like the organization’s.

createKycAccessToken returns a WebSDK token for that check, used the same way as the business token:

curl -s -X POST "$ELE_API_BASE/api/v1/kyc/access-token" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{}'

The token is always for the person who is signed in. No one can get a token for someone else, even an owner or admin. You may add organization_id to the body; then Ele checks that the person may update that organization, but the token is still for the person themselves.

The signed-in person can also submit their name, date of birth, nationality and address in one call with submitInitialUserDetails.

6. Upload documents

getOrganizationOnboardingChecklist lists the documents and fields Ele needs, with the status of each. Any member can read it.

curl -s "$ELE_API_BASE/api/v1/organizations/$ORGANIZATION_ID/onboarding/checklist" \
  -H "Authorization: Bearer $ELE_TOKEN"

For each item with kind set to document:

• key is the document type, such as proof_of_address.
• subject_kyc_entity_id and subject_label say whose document it is: the company, or one of the people behind it. A business with several directors gets one item per director.
• accepted_subtypes lists the kinds of document that satisfy it, such as a bank statement or a utility bill. A subtype’s components are its parts, such as the front and back of a card.
• latest_event explains a rejection or expiry.

Upload the file with uploadDocument, as a multipart form:

curl -s "$ELE_API_BASE/api/v1/documents" \
  -H "Authorization: Bearer $ELE_TOKEN" \
  -H "Idempotency-Key: $KEY" \
  -F "file=@statement.pdf" \
  -F "organization_id=$ORGANIZATION_ID" \
  -F "kyc_entity_id=$SUBJECT_KYC_ENTITY_ID" \
  -F "document_type=proof_of_address" \
  -F "document_subtype_id=$SUBTYPE_ID"

Send the item’s subject_kyc_entity_id as kyc_entity_id. If you leave it out, Ele uploads to the company for a company document, and to the owner for a personal one. When you send a subtype and component, Ele works out document_type from them; a document_type that disagrees is refused.

Some checklist items are fields rather than documents. Read what the organization still owes with getOrganizationProfileGaps, and submit each one with submitOrganizationProfileGap. Each item’s field_spec.form_schema describes the input. An empty data list does not mean the organization is done: read its state from migration, where ready_to_upgrade is true only once every check has passed.

7. See what the organization can do

getOrganizationCapabilities answers “what can this organization do now?”. Any member can call it; owners and admins also get the checklist lines behind each answer.

curl -s "$ELE_API_BASE/api/v1/organizations/$ORGANIZATION_ID/capabilities" \
  -H "Authorization: Bearer $ELE_TOKEN"

verification.stage is the overall state: not_started, action_required, in_review or verified. capabilities has one entry for each thing the organization might do:

key	What it unlocks
fiat_in	Receiving bank transfers.
fiat_out	Paying out to bank accounts.
crypto_in	Receiving crypto deposits.
crypto_out	Paying out to crypto wallets.
card_issuing	Issuing cards.
card_delivery	Delivering physical cards.
signup	Completing sign-up itself.

Each one’s status is available, action_required, in_review, provider_pending (waiting on one of Ele’s partners) or unavailable. blocked_by says why it is not available yet: requirements, signup, provider, funding or market. Being verified does not unlock everything at once: check the capability you need before you offer it.

Individual organizations

An organization with registered_entity set to false belongs to one person: its owner. Ele verifies that person, not a business, and every step below is for the owner alone, signed in with their own session. Your staff cannot do them on the owner’s behalf, so this path cannot run from your server alone: the person creates their own organization, and completes it themselves through your front end.

1. Create the organization, signed in as the person, with registered_entity set to false.

2. Submit the person’s details: name, date of birth, nationality and address with submitInitialUserDetails, or one at a time with submitOnboardingRequirement.

   curl -s "$ELE_API_BASE/api/v1/onboarding/requirements/submissions" \
     -H "Authorization: Bearer $ELE_TOKEN" \
     -H "Idempotency-Key: $KEY" \
     -H 'Content-Type: application/json' \
     -d '{"key": "date_of_birth", "value": {"date_value": "1990-04-12"}}'

3. Get the questionnaire’s IDs from getPersonalQuestionnaireOptions. monthly_income_id and estimated_monthly_volume_id both take an ID from monthly_volumes.

   curl -s "$ELE_API_BASE/api/v1/onboarding/questionnaire-options/personal" \
     -H "Authorization: Bearer $ELE_TOKEN"

4. Submit it with submitKycQuestionnaire. Only the organization’s owner can, and only for an individual organization.

   curl -s "$ELE_API_BASE/api/v1/organizations/$ORGANIZATION_ID/kyc/questionnaire" \
     -H "Authorization: Bearer $ELE_TOKEN" \
     -H "Idempotency-Key: $KEY" \
     -H 'Content-Type: application/json' \
     -d "{\"occupation_id\": \"$OCCUPATION_ID\",
          \"source_of_funds_id\": \"$SOURCE_OF_FUNDS_ID\",
          \"purpose_id\": \"$PURPOSE_ID\",
          \"monthly_income_id\": \"$MONTHLY_INCOME_ID\",
          \"estimated_monthly_volume_id\": \"$MONTHLY_VOLUME_ID\"}"

5. Run the person’s identity check with their own KYC token, as in step 5.

6. Upload any documents the checklist asks for, as in step 6.

Once the person has set the organization up, they can invite your staff to it (see Organizations and roles).

States

A checklist line’s status moves through these states:

status	Meaning	What you do
missing	Nothing submitted yet.	Collect and submit it.
in_review	Submitted, and being checked.	Wait. Poll as described in Staying in sync.
satisfied	Accepted.	Nothing.
rejected	Not accepted. reason says why.	Fix it, then submit it again.
expired	It was accepted, but is out of date.	Submit a current one.

A line with graced set to true is one that sign-up lets the organization finish without until graced_until. Grace applies to sign-up only: another capability may still need the line, so check that capability in step 7 before you offer it, and submit the line before graced_until.

On the document checklist, a document’s status is not_uploaded, pending_review, verified, rejected or expired.

Step-up and approvals

None of the calls in this guide needs step-up or an approval.

What to poll

Checks can take days. Poll getOrganizationCapabilities while a review is under way, and before you offer a feature. Staying in sync suggests how often.

Common errors

Status	type	When	What to do
403	forbidden	The person is not an owner or admin, the business forms were sent for an organization that is not a registered business, or the personal questionnaire was sent for one that is.	Use an owner or admin, or check registered_entity.
422	unprocessable_entity	A KYB token was asked for before the business details were submitted, or for an organization that is not a registered business, or the identity-check provider failed.	Submit step 3 first, then try again.
422	organization_limit_reached	The user already owns as many organizations as organization_limit allows.	Ask your Ele contact to raise the limit.
422	kyc_entity_id_required	An upload left out kyc_entity_id, and Ele could not tell whose document it is.	Send the checklist item’s subject_kyc_entity_id.
422	invalid_request	A field is missing or malformed. details names it.	Fix the request.
429	rate_limited	Too many organizations created in a short time.	Wait, then retry with a new key.

For other types, see Errors.