Skip to main content
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"

email
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)

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

Response

201 - application/json

Created

status
string
Example:

"success"

data
object