Create Individual

Create individual customer

curl --request POST \
  --url https://api-staging.stablestack.xyz/api/individual-customers \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{
  "customer_type": "individual",
  "first_name": "John",
  "middle_name": "Oluwaseun",
  "last_name": "Ola",
  "email": "olajohn3@gmail.com",
  "phone": "+2348918945668",
  "birth_date": "1990-01-15",
  "account_purpose": "PERSONAL_OR_LIVING_EXPENSES",
  "employment_status": "EMPLOYED",
  "expected_monthly_income": 500000,
  "most_recent_occupation": "151211",
  "source_of_funds": "SALARY",
  "registered_address": {
    "street1": "123 Main St",
    "street2": "Suite 456",
    "city": "Lagos",
    "state": "DE",
    "postal_code": "214578",
    "country": "NG"
  },
  "phone_country_code": "+234",
  "account_purpose_explanation": "To save money for future investments and handle personal international transactions",
  "expected_monthly_payments_usd": 1000,
  "acting_as_intermediary": false,
  "tax_identification_number": "TIN987654321",
  "documents": [
    {
      "doc_type": "valid_ids",
      "sub_type": "front",
      "doc_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
      "doc_country": "NG"
    }
  ]
}'

{
  "status": "success",
  "data": {
    "id": "11a3c37f-06bb-4e7c-9813-0e47d47e9e2d",
    "customer_type": "individual",
    "email": "olajohn3@gmail.com",
    "phone": "+2348918945668",
    "created_at": "2025-05-09T16:33:57.844Z",
    "updated_at": "2025-05-09T16:33:57.844Z",
    "status": "active",
    "address": {
      "street1": "123 Main St",
      "street2": "Suite 456",
      "city": "Lagos",
      "state": "DE",
      "postal_code": "214578",
      "country": "NG"
    },
    "personal_info": {
      "first_name": "john",
      "middle_name": "Oluwaseun",
      "last_name": "ola",
      "birth_date": "1990-01-14T23:00:00.000Z"
    },
    "financial_info": {
      "account_purpose": "personal savings",
      "employment_status": "employed",
      "expected_monthly_income": "500000.00",
      "most_recent_occupation": "Software Engineer",
      "source_of_funds": "salary"
    }
  }
}

POST

individual-customers

Create individual customer

curl --request POST \
  --url https://api-staging.stablestack.xyz/api/individual-customers \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '{
  "customer_type": "individual",
  "first_name": "John",
  "middle_name": "Oluwaseun",
  "last_name": "Ola",
  "email": "olajohn3@gmail.com",
  "phone": "+2348918945668",
  "birth_date": "1990-01-15",
  "account_purpose": "PERSONAL_OR_LIVING_EXPENSES",
  "employment_status": "EMPLOYED",
  "expected_monthly_income": 500000,
  "most_recent_occupation": "151211",
  "source_of_funds": "SALARY",
  "registered_address": {
    "street1": "123 Main St",
    "street2": "Suite 456",
    "city": "Lagos",
    "state": "DE",
    "postal_code": "214578",
    "country": "NG"
  },
  "phone_country_code": "+234",
  "account_purpose_explanation": "To save money for future investments and handle personal international transactions",
  "expected_monthly_payments_usd": 1000,
  "acting_as_intermediary": false,
  "tax_identification_number": "TIN987654321",
  "documents": [
    {
      "doc_type": "valid_ids",
      "sub_type": "front",
      "doc_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
      "doc_country": "NG"
    }
  ]
}'

{
  "status": "success",
  "data": {
    "id": "11a3c37f-06bb-4e7c-9813-0e47d47e9e2d",
    "customer_type": "individual",
    "email": "olajohn3@gmail.com",
    "phone": "+2348918945668",
    "created_at": "2025-05-09T16:33:57.844Z",
    "updated_at": "2025-05-09T16:33:57.844Z",
    "status": "active",
    "address": {
      "street1": "123 Main St",
      "street2": "Suite 456",
      "city": "Lagos",
      "state": "DE",
      "postal_code": "214578",
      "country": "NG"
    },
    "personal_info": {
      "first_name": "john",
      "middle_name": "Oluwaseun",
      "last_name": "ola",
      "birth_date": "1990-01-14T23:00:00.000Z"
    },
    "financial_info": {
      "account_purpose": "personal savings",
      "employment_status": "employed",
      "expected_monthly_income": "500000.00",
      "most_recent_occupation": "Software Engineer",
      "source_of_funds": "salary"
    }
  }
}

Creates a new individual customer account with comprehensive KYC processing.

Key Features:

Comprehensive personal information collection
Individual-specific validation rules
Email and phone uniqueness validation
Document upload for compliance
Returns complete personal profile with financial info

Request Body:

{
  "customer_type": "individual",
  "first_name": "john",
  "middle_name": "Oluwaseun",
  "last_name": "ola",
  "email": "olajohn3@gmail.com",
  "phone": "+2348918945668",
  "birth_date": "1990-01-15",
  "account_purpose": "PERSONAL_OR_LIVING_EXPENSES",
  "employment_status": "EMPLOYED",
  "expected_monthly_income": 500000,
  "most_recent_occupation": "151211",
  "source_of_funds": "SALARY",
  "phone_country_code": "+234",
  "account_purpose_explanation": "To save money for future investments and handle personal transactions",
  "expected_monthly_payments_usd": 1000,
  "acting_as_intermediary": false,
  "tax_identification_number": "TIN987654321",
  "user_documents": [
    {
      "doc_type": "valid_ids",
      "sub_type": "front",
      "doc_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
      "doc_country": "NG"
    },
    {
      "doc_type": "utility_bill",
      "doc_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
      "doc_country": "NG"
    }
  ]
}

Enhanced Individual Fields:

phone_country_code: Country code for phone number
account_purpose_explanation: Detailed explanation of account purpose
expected_monthly_payments_usd: Expected monthly payments in USD
acting_as_intermediary: Whether acting as an intermediary for third parties
tax_identification_number: Tax identification number
most_recent_occupation: SOC occupation code (e.g., “151211” for Computer Systems Analyst)
documents: Array of supporting documents for KYC

Document Requirements:

Common document types for individual customers:

valid_ids (passport, driver’s license, national ID)
utility_bill (proof of address)
BANK_STATEMENT
PROOF_OF_ADDRESS
OTHER (additional supporting documents)

Validation Notes:

All monetary amounts can be provided in local currency
Phone numbers should include country codes
Document images can be provided as base64 strings or URLs
Address information is required for compliance

Headers

x-api-key

string

required

Body

application/json

Create a new individual customer account

customer_type

enum<string>

default:individual

required

Available options:

individual

first_name

string

required

First name of the individual

Required string length: 1 - 50

Example:

"John"

last_name

string

required

Last name of the individual

Required string length: 1 - 50

Example:

"Ola"

string<email>

required

Email address of the individual

Example:

"olajohn3@gmail.com"

phone

string

required

Phone number with country code

Example:

"+2348918945668"

birth_date

string<date>

required

Date of birth (must be 18+ years old)

Example:

"1990-01-15"

account_purpose

enum<string>

required

Primary purpose for using the account

Available options:

CHARITABLE_DONATIONS,

ECOMMERCE_RETAIL_PAYMENTS,

INVESTMENT_PURPOSES,

PAYMENTS_TO_FRIENDS_OR_FAMILY_ABROAD,

OTHER,

PAYROLL,

PERSONAL_OR_LIVING_EXPENSES,

PROTECT_WEALTH,

PURCHASE_GOODS_AND_SERVICES,

RECEIVE_PAYMENT_FOR_FREELANCING,

RECEIVE_SALARY,

TAX_OPTIMIZATION,

THIRD_PARTY_MONEY_TRANSMISSION,

TREASURY_MANAGEMENT

Example:

"PERSONAL_OR_LIVING_EXPENSES"

employment_status

enum<string>

required

Current employment status

Available options:

EMPLOYED,

SELF_EMPLOYED,

UNEMPLOYED,

STUDENT,

RETIRED,

OTHER

Example:

"EMPLOYED"

expected_monthly_income

number

required

Expected monthly income in local currency

Required range: x >= 0

Example:

500000

most_recent_occupation

enum<string>

required

Most recent occupation based on SOC codes - use the code value for API requests

Available options:

132011,

272011,

152011,

291291,

519191,

113012,

112011,

413011,

172011,

131011,

194010,

191010,

172021,

452011,

532020,

493011,

532010,

512011,

533011,

452021,

392021,

339011,

392011,

171011,

173011,

119041,

254010,

271010,

192010,

272021,

192021,

291181,

492097,

493021,

493022,

493023,

492091,

396010,

333011,

513011,

395011,

353011,

433011,

433021,

172031,

191020,

194021,

472011,

433031,

472020,

273011,

274010,

434011,

132031,

493031,

131199,

513020,

131021,

517011,

292031,

435011,

472031,

472040,

412010,

472050,

351011,

172041,

519010,

194031,

192030,

111011,

211021,

399011,

291011,

172051,

131030,

537061,

212011,

193033,

292010,

272022,

499091,

271021,

499092,

432099,

113111,

131141,

131041,

151221,

113021,

172061,

151241,

519160,

151299,

151251,

151230,

151211,

492011,

191030,

474011,

472070,

472061,

119021,

499010,

5370XX,

352010,

333012,

434021,

131051,

211019,

412021,

435021,

273092,

434031,

537021,

132041,

434041,

132070,

339091,

519020,

434051,

519030,

514031,

272030,

439021,

15124X,

519080,

319091,

291292,

291020,

475010,

439031,

333021,

292032,

29205X,

291031,

359011,

212021,

272091,

359021,

435032,

419091,

533030,

472080,

475023,

193011,

273041,

119030,

211012,

492092,

173023,

172070,

492093,

49209X,

499051,

512020,

472111,

492096,

252020,

474021,

434061,

3940XX,

119161,

292042,

291214,

512031,

172199,

272099,

119070,

172081,

194040,

192041,

519194,

475022,

436011,

291128,

399031,

475032,

519041,

113013,

119013,

271022,

353023,

474031,

434071,

132051,

433099,

132061,

113031,

332020,

332011,

552010,

471011,

331011,

451011,

331021,

351012,

371011,

371012,

491011,

411012,

431011,

331012,

511011,

331099,

411011,

331091,

333031,

453031,

532031,

271023,

513091,

513092,

513093,

359099,

352021,

513099,

353041,

119051,

454011,

514020,

131131,

119171,

519051,

517021,

433041,

393010,

111021,

19204X,

472121,

452041,

271024,

514033,

395012,

474041,

291299,

211022,

499021,

493040,

499098,

519198,

473010,

474051,

499031,

311121,

359031,

434081,

434161,

113121,

131070,

49904X,

172110,

113051,

537051,

434199,

151212,

519061,

472130,

439041,

413021,

132053,

271025,

273091,

434111,

37201X,

519071,

231020,

231012,

537062,

171012,

373011,

516011,

231011,

436012,

232099,

111031,

254022,

434121,

254031,

292061,

191099,

434131,

499094,

534010,

119081,

454020,

131081,

537063,

514041,

292035,

372012,

439051,

499071,

499043,

131111,

119199,

395092,

499095,

172121,

131161,

112021,

211013,

319011,

172131,

152021,

172141,

274099,

273099,

119111,

319092,

292072,

191040,

436013,

319094,

131121,

211023,

211014,

271026,

514050,

435041,

553010,

551010,

554010,

499044,

172151,

452090,

474090,

292090,

518090,

193090,

493090,

514060,

419010,

514070,

519195,

394031,

533099,

272041,

272042,

119121,

151244,

434141,

273023,

172161,

29203X,

194051,

291151,

291161,

291171,

311131,

195010,

291122,

312010,

439199,

439061,

439071,

152031,

292081,

291041,

434151,

31113X,

5120XX,

21109X,

27102X,

17301X,

2590XX,

17302X,

3930XX,

4750XX,

1320XX,

37301X,

299000,

31909X,

49909X,

1940XX

Example:

"151211"

source_of_funds

enum<string>

required

Primary source of funds

Available options:

BUSINESS_LOANS,

GRANTS,

INTER_COMPANY_FUNDS,

INVESTMENT_PROCEEDS,

LEGAL_SETTLEMENT,

OWNERS_CAPITAL,

PENSION_RETIREMENT,

SALE_OF_ASSETS,

SALES_OF_GOODS_AND_SERVICES,

TAX_REFUND,

THIRD_PARTY_FUNDS,

TREASURY_RESERVES,

ASSETS_SALE,

BUSINESS_INCOME,

CASH_DEPOSITS,

COMPANY_FUNDS,

ECOMMERCE_RESELLER,

GAMBLING_PROCEEDS,

GIFTS,

GOVERNMENT_BENEFITS,

INHERITANCE,

INVESTMENTS_LOANS,

SALARY,

SALE_OF_ASSETS_REAL_ESTATE,

SAVINGS,

SOMEONE_ELSES_FUNDS

Example:

"SALARY"

registered_address

object

required

Address information (used for both individual and business customers)

Show child attributes

middle_name

string

Middle name of the individual (optional)

Maximum length: 50

Example:

"Oluwaseun"

phone_country_code

string

Country code for phone number

Example:

"+234"

account_purpose_explanation

string

Detailed explanation of account purpose

Maximum length: 1000

Example:

"To save money for future investments and handle personal international transactions"

expected_monthly_payments_usd

number

Expected monthly payments in USD

Required range: x >= 0

Example:

1000

acting_as_intermediary

boolean

default:false

Whether acting as an intermediary for third parties

tax_identification_number

string

Tax identification number (optional)

Example:

"TIN987654321"

documents

object[]

Array of supporting documents for KYC verification

Show child attributes

Response

201 - application/json

Created

status

string

Example:

"success"

data

object

Show child attributes

Create Business Get Customer

⌘I

API Documentation

Customers

Wallet Assets

Wallets

Swap

Banks

Beneficiary

Payouts

Transactions

Key Features:

Request Body:

Enhanced Individual Fields:

Document Requirements:

Validation Notes:

Headers

Body

Response

API Documentation

Customers

Wallet Assets

Wallets

Swap

Banks

Beneficiary

Payouts

Transactions

​Key Features:

​Request Body:

​Enhanced Individual Fields:

​Document Requirements:

​Validation Notes:

Headers

Body

Response

Key Features:

Request Body:

Enhanced Individual Fields:

Document Requirements:

Validation Notes: