Skip to content
Ele API

Submit the personal KYC questionnaire

POST
/api/v1/organizations/{organization_id}/kyc/questionnaire
curl --request POST \
  --url https://api.elephants.inc/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/kyc/questionnaire \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "estimated_monthly_volume_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "monthly_income_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "occupation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "purpose_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "source_of_funds_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

Submits the personal onboarding selection IDs for an individual organization owned by the viewer.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
organization_id
required
string format: uuid

Organization ID

Request Bodyrequired

Section titled “Request Bodyrequired”

Personal questionnaire selection IDs

Media typeapplication/json
SubmitPersonalQuestionnaireRequestBody
object
estimated_monthly_volume_id
required
string format: uuid
monthly_income_id
required
string format: uuid
occupation_id
required
string format: uuid
purpose_id
required
string format: uuid
source_of_funds_id
required
string format: uuid

Example generated

{
  "estimated_monthly_volume_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "monthly_income_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "occupation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "purpose_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "source_of_funds_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

Responses

Section titled “Responses”

200

Section titled “200”

Organization with the submitted personal questionnaire

Media typeapplication/json
Organization
object
card_name
required
string | null
company_address
required
string | null
contact_email
required
string | null
country_code
required
string | null
ele_id
required

The organization’s Ele ID, or null until one has been provisioned. Addressing only — never a trust signal; confirm the verified name before sending money.

string | null
<= 30 characters /^[a-z0-9][a-z0-9_-]{1,28}[a-z0-9]$/
id
required
string format: uuid
invoice_name
required
string | null
invoice_notes
required
string | null
is_primary
required

Whether this is your primary organization (see setPrimaryOrganization)

boolean
logo
required
object
url
required
string
name
required
string
permissions
required

Permission keys granted to you in this organization, derived by the server from your role and per-member grants. Membership in this list is the only supported way to decide what to show; the server remains the enforcer.

Array<string>
Allowed values: api_keys.list api_keys.manage approvals.review bank_accounts.list billing_contacts.create billing_contacts.delete billing_contacts.list billing_contacts.update billing_invoices.allocate billing_invoices.create billing_invoices.delete billing_invoices.list_all billing_invoices.list_allocations billing_invoices.list_own billing_invoices.read billing_invoices.resend billing_invoices.submit billing_invoices.update billing_invoices.view_summary bills.cancel bills.create bills.list bills.read bills.update card_entitlements.create card_entitlements.list cards.activate cards.create cards.freeze cards.list_all cards.list_own cards.order_physical cards.provision_google_wallet cards.read cards.reveal cards.set_pin cards.unfreeze cards.update_limit cards.view_usage chains.cancel chains.create chains.decide chains.list chains.read deposit_addresses.list expenses.manage_all expenses.manage_own expenses.read expenses.update feedback.send integrations.connect integrations.disconnect invitations.create invitations.delete invitations.list invitations.resend members.list members.manage onboarding.view_own_requirements onboarding.view_requirements organization.claim_personal_handle organization.generate_upload_url organization.read organization.sudo_session organization.update organization.update_logo organization.update_preferences organization.view_balances organization.view_capabilities organization.view_insights organization.view_kyb_status organization.view_legal_name organization.view_lifetime_spend organization.view_points_balance organization.view_subscription_offers payment_contacts.create payment_contacts.delete payment_contacts.list payment_contacts.update payment_destinations.create payment_destinations.list payment_destinations.update payments.send_crypto payments.send_fiat payments.swap_fiat transactions.list_all transactions.list_own xero.manage
referral_code
required
string | null
registered_entity
required
boolean | null
role
required

Your membership role in this organization. For display only — gate features on permissions, never on the role name.

string
Allowed values: owner admin member
tax_id
required
string | null

Example 

{
  "permissions": [
    "api_keys.list"
  ],
  "role": "owner"
}

400

Section titled “400”

Invalid request parameters or body

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
  "error": {
    "details": "example",
    "message": "example",
    "request_id": "example",
    "step_up": {
      "delivery": "example",
      "expires_at": "2026-04-15T12:00:00Z",
      "id": "example",
      "match_code": "example",
      "methods": [
        "example"
      ],
      "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "webauthn": {
        "allow_credentials": [
          {
            "id": "example",
            "transports": [
              "example"
            ],
            "type": "example"
          }
        ],
        "challenge": "example",
        "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "rp_id": "example",
        "timeout": 1,
        "user_verification": "example"
      }
    },
    "type": "example"
  }
}

401

Section titled “401”

Missing, invalid, or expired bearer token

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
  "error": {
    "details": "example",
    "message": "example",
    "request_id": "example",
    "step_up": {
      "delivery": "example",
      "expires_at": "2026-04-15T12:00:00Z",
      "id": "example",
      "match_code": "example",
      "methods": [
        "example"
      ],
      "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "webauthn": {
        "allow_credentials": [
          {
            "id": "example",
            "transports": [
              "example"
            ],
            "type": "example"
          }
        ],
        "challenge": "example",
        "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "rp_id": "example",
        "timeout": 1,
        "user_verification": "example"
      }
    },
    "type": "example"
  }
}

403

Section titled “403”

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
  "error": {
    "details": "example",
    "message": "example",
    "request_id": "example",
    "step_up": {
      "delivery": "example",
      "expires_at": "2026-04-15T12:00:00Z",
      "id": "example",
      "match_code": "example",
      "methods": [
        "example"
      ],
      "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "webauthn": {
        "allow_credentials": [
          {
            "id": "example",
            "transports": [
              "example"
            ],
            "type": "example"
          }
        ],
        "challenge": "example",
        "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "rp_id": "example",
        "timeout": 1,
        "user_verification": "example"
      }
    },
    "type": "example"
  }
}

404

Section titled “404”

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
  "error": {
    "details": "example",
    "message": "example",
    "request_id": "example",
    "step_up": {
      "delivery": "example",
      "expires_at": "2026-04-15T12:00:00Z",
      "id": "example",
      "match_code": "example",
      "methods": [
        "example"
      ],
      "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "webauthn": {
        "allow_credentials": [
          {
            "id": "example",
            "transports": [
              "example"
            ],
            "type": "example"
          }
        ],
        "challenge": "example",
        "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "rp_id": "example",
        "timeout": 1,
        "user_verification": "example"
      }
    },
    "type": "example"
  }
}

422

Section titled “422”

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
  "error": {
    "details": "example",
    "message": "example",
    "request_id": "example",
    "step_up": {
      "delivery": "example",
      "expires_at": "2026-04-15T12:00:00Z",
      "id": "example",
      "match_code": "example",
      "methods": [
        "example"
      ],
      "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "webauthn": {
        "allow_credentials": [
          {
            "id": "example",
            "transports": [
              "example"
            ],
            "type": "example"
          }
        ],
        "challenge": "example",
        "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "rp_id": "example",
        "timeout": 1,
        "user_verification": "example"
      }
    },
    "type": "example"
  }
}

429

Section titled “429”

Too many requests

Media typeapplication/json
RateLimitedError
object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string
error
required
object
type
required
string
Allowed value: rate_limited

Example 

{
  "error": {
    "type": "rate_limited"
  }
}

Headers

Section titled “Headers”
Retry-After
required
string

How long to wait before retrying, expressed as delay seconds or an HTTP date

500

Section titled “500”

Unexpected server error

Media typeapplication/json
Error

Error response. error.type is the machine-readable code — branch on it, never on error.message or the HTTP status. error.message is display-grade prose safe to render to a user; when a failure has no specific copy it falls back to a generic sentence, so it never carries a machine code. Unrecognised failures collapse to the generic unprocessable_entity code, so treat type as an open enum: match the codes you handle and fall through to a default branch for the rest.

object
error
required
object
details

Structured error details (e.g. validation errors), when present

message
required

Display-grade message, safe to render verbatim. Never a machine code — do not branch on it.

string
request_id

Correlation ID for this request (also in the x-request-id response header). Include it when contacting support.

string
step_up
Any of:
StepUpChallenge
object
delivery
required

Method used to deliver this challenge

string
expires_at
required

Challenge expiry

string | null format: date-time
id
required

Sudo session ID returned to completeStepUp

string
match_code
required

3-digit number-matching code. This response is the ORIGINATING surface: display the code; a user approving from the Ele mobile app is asked to enter it. Null only for challenges minted before match codes existed.

string | null
methods
required

Available verification methods

Array<string>
step_up_authentication_id
required

The step-up authentication this challenge was minted from — a DIFFERENT id from id (the sudo session). completeStepUp takes id as sudo_session_id; requestStepUpFallback takes this one.

string format: uuid
webauthn
required
Any of:
PasskeyAuthenticationOptions
object
allow_credentials
required
Array<object>
object
id
required
string
transports
required
Array<string>
type
required
string
challenge
required
string
challenge_id
required
string format: uuid
rp_id
required
string
timeout
required
integer
user_verification
required
string
type
required

Machine-readable error code from a stable vocabulary (open enum — handle unknown values)

string

Example generated

{
  "error": {
    "details": "example",
    "message": "example",
    "request_id": "example",
    "step_up": {
      "delivery": "example",
      "expires_at": "2026-04-15T12:00:00Z",
      "id": "example",
      "match_code": "example",
      "methods": [
        "example"
      ],
      "step_up_authentication_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "webauthn": {
        "allow_credentials": [
          {
            "id": "example",
            "transports": [
              "example"
            ],
            "type": "example"
          }
        ],
        "challenge": "example",
        "challenge_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
        "rp_id": "example",
        "timeout": 1,
        "user_verification": "example"
      }
    },
    "type": "example"
  }
}