User Management

Overview

Before creating virtual accounts, you need to create users in the Kira system. Each user represents an individual or business that will own one or more virtual accounts.

Automatic Verification

When you create a user with all required fields, Kira automatically triggers identity verification (KYC/KYB) in the background. This means:

No additional API calls needed - Verification starts automatically
Faster onboarding - Users don't need to complete a separate verification step
Webhook notifications - You'll receive user.verification.accepted or user.verification.failed events

The response includes a verification_triggered field indicating whether automatic verification was started.

Required Fields for Automatic Verification

Note: USA vs International is determined by the address_country field. See the Verification Guide for the complete list with descriptions.

Individual Users

Field	USA Residents	International
`first_name`	Required	Required
`last_name`	Required	Required
`birth_date`	Required	Required
`email`	Required	Required
`phone`	Required	Required
`address_street`	Required	Required
`address_city`	Required	Required
`address_state`	Required	Required
`address_zip_code`	Required	Required
`address_country`	Required	Required
`document_type`	Required	Required
`document_number`	Required	Required
`document_country`	Required	Required
`nationality`	Required	Required
`gender`	Required	Required
`ssn` (via `identifying_information`)	Required	-
`tax_id` (via `identifying_information`)	-	Required
`source_of_funds`	Required	Required
`account_purpose`	Required	Required
`employment_status`	Required	Required
`occupation`	Required	Required
`pep_status`	Required	Required
`expected_monthly_payments`	-	Required
`identifying_information` with `file_proof_of_address` document	Required	Required
`identifying_information` with Government ID + `front` document	Required	Required

Business Users

Field	USA Businesses	International
`company_name`	Required	Required
`doing_business_as`	Required	Required
`business_type`	Required	Required
`business_industry`	Required	Required
`formation_date`	Required	Required
`formation_state`	Required	Required
`email`	Required	Required
`phone`	Required	Required
`address_street`	Required	Required
`address_city`	Required	Required
`address_state`	Required	Required
`address_zip_code`	Required	Required
`address_country`	Required	Required
`document_type`	Required	Required
`document_number`	Required	Required
`document_country`	Required	Required
`ein`	Required	-
`tax_id` (via `identifying_information`)	-	Required
`representative_first_name`	Required	Required
`representative_last_name`	Required	Required
`representative_title`	Required	Required
`representative_birth_date`	Required	Required
`representative_ssn`	Required	-
`business_description`	Required	Required
`business_website`	Required	Required
`source_of_funds`	Required	Required
`account_purpose`	Required	Required
`pep_status`	Required	Required
`expected_monthly_payments`	-	Required
`identifying_information` with `file_proof_of_address`	Required	Required
`identifying_information` with `file_business_formation`	Required	Required
`associated_persons` with Government ID + `front` document	Required	Required

Create a User

Endpoint

POST /v1/users

Headers

Header	Required	Description
`Authorization`	Yes	Bearer token from authentication
`x-api-key`	Yes	Your API key
`Content-Type`	Yes	Must be `application/json`
`idempotency-key`	Yes	UUID to prevent duplicate user creation

Individual User

Field Descriptions

Basic Information

Field	Type	Required	Description
`type`	string	Yes	Must be `"individual"`
`email`	string	Yes	Valid email address
`first_name`	string	Yes	User's first name
`last_name`	string	Yes	User's last name
`middle_name`	string	No	User's middle name
`phone`	string	No*	Phone number in E.164 format (e.g., +1234567890). *Required for KYC
`birth_date`	string	No*	Date of birth in YYYY-MM-DD format. User must be 18+ years old. *Required for KYC
`nationality`	string	No	3-letter ISO country code (e.g., "USA", "MEX")
`gender`	string	No	Gender: `"male"`, `"female"`, or `"other"`
`external_id`	string	No	Your internal reference ID for this user

Address Fields

Field	Type	Required	Description
`address_street`	string	No*	Street address. *Required for KYC
`address_street_2`	string	No	Apartment, suite, unit, etc.
`address_city`	string	No*	City. *Required for KYC
`address_state`	string	No*	State or province code. *Required for KYC
`address_zip_code`	string	No*	ZIP or postal code. *Required for KYC
`address_country`	string	No*	3-letter ISO country code. *Required for KYC

Identifying Information

The identifying_information array contains tax IDs and government-issued identification documents.

Field	Type	Required	Description
`identifying_information`	array	No*	Array of identification objects. *Required for KYC

Identifying Information Object:

Field	Type	Required	Description
`type`	string	Yes	Type of identification (see table below)
`issuing_country`	string	Yes	3-letter ISO country code
`number`	string	No*	ID number. *Required for tax IDs
`expiration`	string	No	Expiration date in YYYY-MM-DD format
`description`	string	No	Additional description
`documents`	array	No*	Array of document files. *Required for government IDs

Identification Types:

Type	Category	Documents Required	Description
`passport`	Government ID	Yes (front)	International passport
`national_id`	Government ID	Yes (front, back)	National ID card (INE, Cedula, etc.)
`drivers_license`	Government ID	Yes (front, back)	Driver's license
`state_or_provincial_id`	Government ID	Yes (front, back)	State-issued ID
`permanent_residency_id`	Government ID	Yes (front, back)	Permanent residency card
`visa`	Government ID	Yes (front)	Travel visa
`military_id`	Government ID	Yes (front, back)	Military identification
`matriculate_id`	Government ID	Yes (front, back)	Matricula consular
`ssn`	Tax ID	No	USA Social Security Number
`itin`	Tax ID	No	USA Individual Taxpayer ID
`tax_id`	Tax ID	No	Generic tax identifier — use this for all international (non-USA) users
`curp`	Tax ID	No	Mexico CURP (accepted by the API, but use `tax_id` for product eligibility)
`rfc`	Tax ID	No	Mexico RFC (accepted by the API, but use `tax_id` for product eligibility)
`cpf`	Tax ID	No	Brazil CPF (accepted by the API, but use `tax_id` for product eligibility)
`tin`	Tax ID	No	Generic Tax ID Number (accepted by the API, but use `tax_id` for product eligibility)
`nuip`	Tax ID	No	Colombia NUIP (accepted by the API, but use `tax_id` for product eligibility)
`proof_of_address`	Document	Yes (file)	Proof of address (utility bill, bank statement)
`source_of_wealth`	Document	Yes (file)	Source of wealth document. Required for `usa-virtual-accounts` eligibility.
`business_formation`	Document	Yes (file)	Business formation document (articles of incorporation)

Document Object:

Field	Type	Required	Description
`type`	string	Yes	Document type (see values below)
`file`	string	Yes	Base64 data URI only.
`description`	string	No	Document description

Document Type Values (Individual):

Type	Description
`front`	Front of ID document
`back`	Back of ID document
`selfie`	Selfie photo for identity verification
`file_proof_of_address`	Proof of address document (utility bill, bank statement)
`file_source_of_wealth`	Source of wealth document

Document Type Values (Business):

Type	Description
`file_proof_of_address`	Proof of business address (utility bill, bank statement)
`file_business_formation`	Business formation document (articles of incorporation, bylaws)
`file_source_of_wealth`	Source of wealth document

Supported file formats: JPEG, PNG, PDF (max 10MB)

Compliance Fields

Field	Type	Required	Description
`pep_status`	boolean	No*	Is the user a Politically Exposed Person? *Required for KYC
`source_of_funds`	string	No*	Origin of funds (see values below). *Required for KYC
`account_purpose`	string	No*	Purpose of the account (see values below). *Required for KYC
`expected_monthly_payments`	string	No	Expected monthly volume (see values below)
`employment_status`	string	No*	Employment status (see values below). *Required for KYC and ACT virtual accounts
`current_employer`	string	No	Name of current employer. Applicable when `employment_status` is `employed`
`income_source`	string	No	Source of income. Applicable when `employment_status` is `self_employed`, `retired`, or `unemployed`
`occupation`	string	No*	User's occupation. *Required for KYC
`immigration_status`	string	No*	U.S. residency status for non-U.S. citizens. *Required for ACT virtual accounts (international individuals)
`additional_info`	object	No*	Additional information for ACT virtual accounts. *Required for ACT (international individuals and international businesses)

Source of Funds Values (Individual KYC): salary, self_employment_income, investment_proceeds, savings_inheritance_gift

Account Purpose Values (Individual KYC): receive_payments, manage_professional_income, make_payments, manage_personal_funds, investment_trading

Expected Monthly Payments Values: 0_4999, 5000_9999, 10000_49999, 50000_plus

Employment Status Values: employed, self_employed, unemployed, retired, student

Immigration Status Values (ACT): Permanent U.S. Resident, Non-Permanent U.S. Resident, Non-Resident of U.S.

Additional Info Fields (ACT) — for international individuals and international businesses:

Required for eligibility:

Field	Type	Required	Description
`has_us_bank_account`	`Yes` / `No`	Yes	Does the applicant have a U.S. bank account?
`has_denied_bank_account`	`Yes` / `No`	Yes	Has the applicant been denied opening a U.S. bank account?
`denied_bank_account_explain`	string	When `Yes`	Explanation required when `has_denied_bank_account` is `Yes`

Optional (default to No if not provided, validated at ACT submission):

Field	Type	Required	Description
`past_owner_interaction`	`Yes` / `No`	No	Prior adverse interactions (tax audits, regulatory sanctions, etc.)?
`past_owner_interaction_explain`	string	When `Yes`	Explanation required when `past_owner_interaction` is `Yes`
`any_politically_exposed_person`	`Yes` / `No`	No	Is the applicant or any associated person a PEP?
`any_politically_exposed_person_explain`	string	When `Yes`	Explanation required when `any_politically_exposed_person` is `Yes`
`past_business_interaction`	`Yes` / `No`	No	Has the business had prior adverse interactions? (international businesses only)
`past_business_interaction_explain`	string	When `Yes`	Explanation required when `past_business_interaction` is `Yes`

Other Fields

Field	Type	Required	Description
`metadata`	object	No	Custom key-value pairs for your reference
`documents`	array	No	Legacy document array (use `identifying_information.documents` instead)

Example Request - Individual USA

curl -X POST https://api.balampay.com/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: 550e8400-e29b-41d4-a716-446655440001" \
  -d '{
    "type": "individual",
    "first_name": "John",
    "last_name": "Doe",
    "middle_name": "William",
    "email": "[email protected]",
    "phone": "+12025551234",
    "birth_date": "1990-01-15",
    "nationality": "USA",
    "gender": "male",
    "external_id": "your-internal-id-123",

    "address_street": "123 Main Street",
    "address_street_2": "Apt 4B",
    "address_city": "San Francisco",
    "address_state": "CA",
    "address_zip_code": "94105",
    "address_country": "USA",

    "identifying_information": [
      {
        "type": "ssn",
        "issuing_country": "USA",
        "number": "123-45-6789"
      },
      {
        "type": "drivers_license",
        "issuing_country": "USA",
        "number": "D1234567",
        "expiration": "2028-01-15",
        "documents": [
          {
            "type": "front",
            "file": "data:image/jpeg;base64,{{front}}"
          },
          {
            "type": "back",
            "file": "data:image/jpeg;base64,{{back}}"
          },
          {
            "type": "file_proof_of_address",
            "file": "data:image/jpeg;base64,{{proof_of_address}}"
          }
        ]
      }
    ],

    "pep_status": false,
    "source_of_funds": "salary",
    "account_purpose": "manage_personal_funds",
    "employment_status": "employed",
    "current_employer": "Acme Corp",
    "occupation": "Software Engineer",
    "expected_monthly_payments": "5000_9999"
  }'

Example Request - Individual International (Mexico)

curl -X POST https://api.balampay.com/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: 550e8400-e29b-41d4-a716-446655440002" \
  -d '{
    "type": "individual",
    "first_name": "Maria",
    "last_name": "Garcia",
    "middle_name": "Lopez",
    "email": "[email protected]",
    "phone": "+5215512345678",
    "birth_date": "1988-05-20",
    "nationality": "MEX",
    "gender": "female",
    "external_id": "mex-user-456",

    "address_street": "Av. Reforma 222",
    "address_street_2": "Piso 10",
    "address_city": "Ciudad de Mexico",
    "address_state": "CDMX",
    "address_zip_code": "06600",
    "address_country": "MEX",

    "identifying_information": [
      {
        "type": "curp",
        "issuing_country": "MEX",
        "number": "GARM880520MDFRRL09"
      },
      {
        "type": "rfc",
        "issuing_country": "MEX",
        "number": "GARM880520XXX"
      },
      {
        "type": "national_id",
        "issuing_country": "MEX",
        "number": "1234567890123",
        "expiration": "2030-05-20",
        "documents": [
          {
            "type": "front",
            "file": "data:image/jpeg;base64,{{front}}"
          },
          {
            "type": "back",
            "file": "data:image/jpeg;base64,{{back}}"
          },
          {
            "type": "file_proof_of_address",
            "file": "data:image/jpeg;base64,{{proof_of_address}}"
          }
        ]
      }
    ],

    "pep_status": false,
    "source_of_funds": "salary",
    "account_purpose": "make_payments",
    "employment_status": "employed",
    "current_employer": "Empresa S.A.",
    "occupation": "Contador"
  }'

Business User

Field Descriptions

Basic Information

Field	Type	Required	Description
`type`	string	Yes	Must be `"business"`
`business_legal_name`	string	Yes	Legal registered business name
`email`	string	Yes	Business contact email
`business_trade_name`	string	No	Trade name if different from legal name
`doing_business_as`	string	No	DBA name
`business_type`	string	No*	Business entity type. *Required for KYC
`business_description`	string	No	Description of business activities
`business_industry`	array	No	Array of NAICS subsector codes (see values below)
`business_website`	string	No	Business website URL
`phone`	string	No	Business phone number
`external_id`	string	No	Your internal reference ID

Business Type Values: limited_liability_company, corporation, general_partnership, limited_liability_partnership, sole_proprietor, non_profit, trust, government_organization, publicly_traded_company

Business Industry Values (NAICS Subsector Codes)

Sector	Values
Agriculture, Forestry, Fishing and Hunting	`crop_production`, `animal_production`, `forestry_logging`, `fishing_hunting_trapping`, `support_activities_agriculture_forestry`
Mining, Quarrying, and Oil and Gas Extraction	`oil_gas_extraction`, `mining_except_oil_gas`, `support_activities_mining`
Utilities	`utilities`
Construction	`construction_of_buildings`, `heavy_civil_engineering_construction`, `specialty_trade_contractors`
Manufacturing	`food_manufacturing`, `beverage_tobacco_product_manufacturing`, `textile_mills`, `textile_product_mills`, `apparel_manufacturing`, `leather_allied_product_manufacturing`, `wood_product_manufacturing`, `paper_manufacturing`, `printing_related_support_activities`, `petroleum_coal_products_manufacturing`, `chemical_manufacturing`, `plastics_rubber_products_manufacturing`, `nonmetallic_mineral_product_manufacturing`, `primary_metal_manufacturing`, `fabricated_metal_product_manufacturing`, `machinery_manufacturing`, `computer_electronic_product_manufacturing`, `electrical_equipment_appliance_component_manufacturing`, `transportation_equipment_manufacturing`, `furniture_related_product_manufacturing`, `miscellaneous_manufacturing`
Wholesale Trade	`merchant_wholesalers_durable_goods`, `merchant_wholesalers_nondurable_goods`, `wholesale_electronic_markets_agents_brokers`
Retail Trade	`motor_vehicle_parts_dealers`, `furniture_home_furnishings_stores`, `electronics_appliance_stores`, `building_material_garden_equipment_supplies_dealers`, `food_beverage_stores`, `health_personal_care_stores`, `gasoline_stations`, `clothing_accessories_stores`, `sporting_goods_hobby_book_music_stores`, `general_merchandise_stores`, `miscellaneous_store_retailers`, `nonstore_retailers`
Transportation and Warehousing	`air_transportation`, `rail_transportation`, `water_transportation`, `truck_transportation`, `transit_ground_passenger_transportation`, `pipeline_transportation`, `scenic_sightseeing_transportation`, `support_activities_transportation`, `postal_service`, `couriers_messengers`, `warehousing_storage`
Information	`publishing_industries`, `motion_picture_sound_recording_industries`, `broadcasting`, `internet_publishing_broadcasting`, `telecommunications`, `data_processing_hosting_related_services`, `other_information_services`
Finance and Insurance	`monetary_authorities_central_bank`, `credit_intermediation_related_activities`, `securities_commodity_contracts_financial_investments`, `insurance_carriers_related_activities`, `funds_trusts_other_financial_vehicles`
Real Estate and Rental and Leasing	`real_estate`, `rental_leasing_services`, `lessors_nonfinancial_intangible_assets`
Professional, Scientific, and Technical Services	`professional_scientific_technical`
Management of Companies and Enterprises	`management_of_companies`
Administrative and Support and Waste Management	`administrative_support_services`, `waste_management_remediation_services`
Educational Services	`educational_services`
Health Care and Social Assistance	`ambulatory_health_care_services`, `hospitals`, `nursing_residential_care_facilities`, `social_assistance`
Arts, Entertainment, and Recreation	`performing_arts_spectator_sports`, `museums_historical_sites`, `amusement_gambling_recreation_industries`
Accommodation and Food Services	`accommodation`, `food_services_drinking_places`
Other Services	`repair_maintenance`, `personal_laundry_services`, `religious_grantmaking_civic_professional_organizations`, `private_households`
Public Administration	`public_administration`

Formation Information

Field	Type	Required	Description
`formation_date`	string	No*	Date of incorporation in YYYY-MM-DD format. *Required for KYC
`formation_state`	string	No*	State/region where business was formed. *Required for KYC
`formation_country`	string	No	3-letter ISO country code where business was incorporated (e.g., "USA", "MEX")

Address Fields

Field	Type	Required	Description
`address_street`	string	No*	Registered business address. *Required for KYC
`address_street_2`	string	No	Suite, floor, etc.
`address_city`	string	No*	City. *Required for KYC
`address_state`	string	No*	State or province. *Required for KYC
`address_zip_code`	string	No*	ZIP or postal code. *Required for KYC
`address_country`	string	No*	3-letter ISO country code. *Required for KYC

Tax Identifiers

Field	Type	Required	Description
`ein`	string	No*	USA Employer Identification Number. *Required for USA businesses
`rfc`	string	No*	Mexico RFC. *Required for Mexico businesses
`cnpj`	string	No*	Brazil CNPJ. *Required for Brazil businesses

Legal Representative

Field	Type	Required	Description
`representative_first_name`	string	No*	Representative's first name. *Required for KYC
`representative_last_name`	string	No*	Representative's last name. *Required for KYC
`representative_title`	string	No*	Representative's title (CEO, Director, etc.). *Required for KYC
`representative_birth_date`	string	No*	Representative's DOB in YYYY-MM-DD format. *Required for KYC
`representative_ssn`	string	No*	Representative's SSN (USA only). *Required for USA KYC

Associated Persons (UBOs and Signers)

The associated_persons array contains information about Ultimate Beneficial Owners (UBOs) and authorized signers.

Field	Type	Required	Description
`associated_persons`	array	No*	Array of associated person objects. *Required for KYC

Associated Person Object:

Field	Type	Required	Description
`first_name`	string	Yes	Person's first name
`last_name`	string	Yes	Person's last name
`middle_name`	string	No	Person's middle name
`email`	string	No	Person's email
`birth_date`	string	No*	Date of birth in YYYY-MM-DD. *Required for KYC
`nationality`	string	No	3-letter country code
`title`	string	No	Position/title in the company
`has_ownership`	boolean	No	Does this person have ownership?
`ownership_percentage`	number	No	Percentage owned (0-100)
`has_control`	boolean	No	Does this person have control?
`is_signer`	boolean	No	Is this person an authorized signer?
`ssn`	string	No	SSN (USA persons only)
`address_street`	string	No	Street address
`address_city`	string	No	City
`address_state`	string	No	State/province
`address_zip_code`	string	No	ZIP/postal code
`address_country`	string	No	3-letter country code
`identifying_information`	array	No*	Government IDs. *Required for KYC

Note: Each associated person must include identifying_information with at least one government ID containing a documents array with a front image of their identification document.

Identifying Information (Business Documents)

Field	Type	Required	Description
`identifying_information`	array	No	Business formation documents and tax IDs

Business Identification Types:

Type	Category	Description
`business_formation`	Document	Articles of incorporation, bylaws, etc.
`proof_of_address`	Document	Business address verification
`ein`	Tax ID	USA Employer Identification Number
`nit`	Tax ID	Colombia NIT

Compliance Fields

Field	Type	Required	Description
`pep_status`	boolean	No*	Any associated person is a PEP? *Required for KYC
`source_of_funds`	string	No*	Origin of business funds. *Required for KYC
`account_purpose`	string	No*	Purpose of the account. *Required for KYC
`expected_monthly_payments`	string	No	Expected monthly volume
`has_material_intermediary_ownership`	boolean	No	Is there intermediary ownership?

Other Fields

Field	Type	Required	Description
`metadata`	object	No	Custom key-value pairs
`documents`	array	No	Additional business documents

Example Request - Business USA

curl -X POST https://api.balampay.com/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: 550e8400-e29b-41d4-a716-446655440003" \
  -d '{
    "type": "business",
    "business_legal_name": "Acme Technology Inc.",
    "business_trade_name": "Acme Tech",
    "doing_business_as": "Acme",
    "email": "[email protected]",
    "phone": "+14155551234",
    "business_type": "corporation",
    "business_description": "SaaS platform for enterprise solutions",
    "business_industry": ["data_processing_hosting_related_services", "computer_electronic_product_manufacturing"],
    "business_website": "https://acmetech.com",
    "external_id": "business-usa-789",

    "formation_date": "2018-03-15",
    "formation_state": "DE",

    "address_street": "100 Market Street",
    "address_street_2": "Suite 500",
    "address_city": "San Francisco",
    "address_state": "CA",
    "address_zip_code": "94105",
    "address_country": "USA",

    "ein": "12-3456789",

    "representative_first_name": "Robert",
    "representative_last_name": "Smith",
    "representative_title": "CEO",
    "representative_birth_date": "1975-08-22",
    "representative_ssn": "987-65-4321",

    "associated_persons": [
      {
        "first_name": "Robert",
        "last_name": "Smith",
        "email": "[email protected]",
        "birth_date": "1975-08-22",
        "has_ownership": true,
        "ownership_percentage": 60,
        "has_control": true,
        "is_signer": true,
        "title": "CEO",
        "ssn": "987-65-4321",
        "address_street": "456 Oak Avenue",
        "address_city": "Palo Alto",
        "address_state": "CA",
        "address_zip_code": "94301",
        "address_country": "USA",
        "identifying_information": [
          {
            "type": "drivers_license",
            "issuing_country": "USA",
            "number": "CA12345678",
            "documents": [
              {
                "type": "front",
                "file": "data:image/jpeg;base64,/9j/4AAQ..."
              },
              {
                "type": "back",
                "file": "data:image/jpeg;base64,/9j/4AAQ..."
              }
            ]
          }
        ]
      },
      {
        "first_name": "Sarah",
        "last_name": "Johnson",
        "email": "[email protected]",
        "birth_date": "1980-11-10",
        "has_ownership": true,
        "ownership_percentage": 40,
        "has_control": false,
        "is_signer": false,
        "title": "Co-founder",
        "ssn": "111-22-3333",
        "address_street": "789 Pine Street",
        "address_city": "San Jose",
        "address_state": "CA",
        "address_zip_code": "95113",
        "address_country": "USA",
        "identifying_information": [
          {
            "type": "passport",
            "issuing_country": "USA",
            "number": "987654321",
            "expiration": "2029-11-10",
            "documents": [
              {
                "type": "front",
                "file": "data:image/jpeg;base64,/9j/4AAQ..."
              }
            ]
          }
        ]
      }
    ],

    "identifying_information": [
      {
        "type": "business_formation",
        "issuing_country": "USA",
        "description": "Certificate of Incorporation",
        "documents": [
          {
            "type": "file_business_formation",
            "file": "data:application/pdf;base64,JVBERi0xLjQ..."
          }
        ]
      }
    ],

    "pep_status": false,
    "source_of_funds": "sales_of_goods_and_services",
    "account_purpose": "receive_payments_for_goods_and_services",
    "expected_monthly_payments": "50000_plus",
    "has_material_intermediary_ownership": false
  }'

Example Request - Business International (Mexico)

curl -X POST https://api.balampay.com/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: 550e8400-e29b-41d4-a716-446655440004" \
  -d '{
    "type": "business",
    "business_legal_name": "Tecnologia Avanzada S.A. de C.V.",
    "business_trade_name": "TecAvanzada",
    "doing_business_as": "TecAv",
    "email": "[email protected]",
    "phone": "+5215598765432",
    "business_type": "corporation",
    "business_description": "Desarrollo de software empresarial",
    "business_industry": ["data_processing_hosting_related_services", "professional_scientific_technical"],
    "business_website": "https://tecavanzada.mx",
    "external_id": "mex-business-001",

    "formation_date": "2015-06-01",
    "formation_state": "CDMX",

    "address_street": "Paseo de la Reforma 505",
    "address_street_2": "Piso 20",
    "address_city": "Ciudad de Mexico",
    "address_state": "CDMX",
    "address_zip_code": "06500",
    "address_country": "MEX",

    "rfc": "TAV150601XXX",

    "representative_first_name": "Carlos",
    "representative_last_name": "Hernandez",
    "representative_title": "Director General",
    "representative_birth_date": "1970-02-14",

    "associated_persons": [
      {
        "first_name": "Carlos",
        "last_name": "Hernandez",
        "email": "[email protected]",
        "birth_date": "1970-02-14",
        "has_ownership": true,
        "ownership_percentage": 70,
        "has_control": true,
        "is_signer": true,
        "title": "Director General",
        "nationality": "MEX",
        "address_street": "Av. Insurgentes Sur 1000",
        "address_city": "Ciudad de Mexico",
        "address_state": "CDMX",
        "address_zip_code": "03100",
        "address_country": "MEX",
        "identifying_information": [
          {
            "type": "national_id",
            "issuing_country": "MEX",
            "number": "HERC700214HDFRRL01",
            "documents": [
              {
                "type": "front",
                "file": "data:image/jpeg;base64,/9j/4AAQ..."
              },
              {
                "type": "back",
                "file": "data:image/jpeg;base64,/9j/4AAQ..."
              }
            ]
          }
        ]
      },
      {
        "first_name": "Ana",
        "last_name": "Martinez",
        "email": "[email protected]",
        "birth_date": "1982-09-25",
        "has_ownership": true,
        "ownership_percentage": 30,
        "has_control": false,
        "is_signer": true,
        "title": "Directora Financiera",
        "nationality": "MEX",
        "address_street": "Calle Durango 200",
        "address_city": "Ciudad de Mexico",
        "address_state": "CDMX",
        "address_zip_code": "06700",
        "address_country": "MEX",
        "identifying_information": [
          {
            "type": "passport",
            "issuing_country": "MEX",
            "number": "G12345678",
            "expiration": "2030-09-25",
            "documents": [
              {
                "type": "front",
                "file": "data:image/jpeg;base64,/9j/4AAQ..."
              }
            ]
          }
        ]
      }
    ],

    "identifying_information": [
      {
        "type": "business_formation",
        "issuing_country": "MEX",
        "description": "Acta Constitutiva",
        "documents": [
          {
            "type": "file_business_formation",
            "file": "data:application/pdf;base64,JVBERi0xLjQ..."
          }
        ]
      },
      {
        "type": "proof_of_address",
        "issuing_country": "MEX",
        "description": "Comprobante de domicilio fiscal",
        "documents": [
          {
            "type": "file_proof_of_address",
            "file": "data:application/pdf;base64,JVBERi0xLjQ..."
          }
        ]
      }
    ],

    "pep_status": false,
    "source_of_funds": "sales_of_goods_and_services",
    "account_purpose": "receive_payments_for_goods_and_services",
    "expected_monthly_payments": "10000_49999"
  }'

Response

Success Response

Status: 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "individual",
  "email": "[email protected]",
  "status": "CREATED",
  "verification_status": "unverified",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "metadata": {
    "ssn": "123-45-6789",
    "occupation": "Software Engineer",
    "current_employer": "Acme Corp",
    "pep_status": false,
    "external_id": "your-internal-id-123",
    "account_purpose": "manage_personal_funds",
    "source_of_funds": "salary",
    "employment_status": "employed",
    "expected_monthly_payments": "5000_9999"
  },
  "first_name": "John",
  "last_name": "Doe",
  "middle_name": "William",
  "phone": "+12025551234",
  "birth_date": "1990-01-15",
  "nationality": "USA",
  "gender": "male",
  "residential_address": {
    "street_line_1": "123 Main Street",
    "street_line_2": "Apt 4B",
    "city": "San Francisco",
    "subdivision": "CA",
    "postal_code": "94105",
    "country": "USA"
  },
  "verification_triggered": true,
  "eligible_products": [
    {
      "product_id": "f4666460-1cb4-4030-8e78-6d67939c1ff1",
      "product_code": "usa-virtual-accounts",
      "product_name": "USA Virtual Accounts",
      "eligible": false
    },
    {
      "product_id": "7be91e3b-be09-48a6-8778-b856d5e0a97d",
      "product_code": "virtual_account",
      "product_name": "Virtual Account",
      "eligible": false
    },
    {
      "product_id": "4d1a6f16-2842-408d-973c-0492e5a59686",
      "product_code": "payout",
      "product_name": "Payout",
      "eligible": false
    }
  ]
}

Response Fields

Field	Description
`id`	Unique user identifier (UUID)
`status`	KYC status: `CREATED`, `VERIFYING`, `VERIFIED`, `REJECTED`, `REVIEW`
`verification_status`	Legacy field (deprecated) - use `status` instead
`verification_triggered`	`true` if automatic verification was started, `false` if required fields are missing
`eligible_products`	Array of products the user is eligible for based on their data
`created_at`	Timestamp when user was created
`updated_at`	Timestamp of last update

Get User Details

Endpoint

GET /v1/users/{userId}

Example Request

curl -X GET https://api.balampay.com/v1/users/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "individual",
  "email": "[email protected]",
  "status": "VERIFIED",
  "verification_status": "verified",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T12:00:00Z",
  "metadata": {
    "ssn": "123-45-6789",
    "occupation": "Software Engineer",
    "current_employer": "Acme Corp",
    "pep_status": false,
    "external_id": "your-internal-id-123",
    "account_purpose": "manage_personal_funds",
    "source_of_funds": "salary",
    "employment_status": "employed",
    "expected_monthly_payments": "5000_9999"
  },
  "first_name": "John",
  "last_name": "Doe",
  "middle_name": "William",
  "phone": "+12025551234",
  "birth_date": "1990-01-15",
  "nationality": "USA",
  "gender": "male",
  "residential_address": {
    "street_line_1": "123 Main Street",
    "street_line_2": "Apt 4B",
    "city": "San Francisco",
    "subdivision": "CA",
    "postal_code": "94105",
    "country": "USA"
  },
  "verification_triggered": true,
  "eligible_products": [
    {
      "product_id": "f4666460-1cb4-4030-8e78-6d67939c1ff1",
      "product_code": "usa-virtual-accounts",
      "product_name": "USA Virtual Accounts",
      "eligible": true
    },
    {
      "product_id": "7be91e3b-be09-48a6-8778-b856d5e0a97d",
      "product_code": "virtual_account",
      "product_name": "Virtual Account",
      "eligible": true
    },
    {
      "product_id": "4d1a6f16-2842-408d-973c-0492e5a59686",
      "product_code": "payout",
      "product_name": "Payout",
      "eligible": true
    }
  ]
}

User Status

The status field indicates the KYC verification state of the user:

Status	Description
`CREATED`	User created, verification may be pending or not triggered
`VERIFYING`	Automatic verification is in progress
`VERIFIED`	User has successfully completed identity verification
`REJECTED`	Verification was rejected
`REVIEW`	Verification requires manual review

Verification Status (Deprecated)

Note: The verification_status field is deprecated. Use status instead.

Status	Description
`unverified`	User created, not yet verified
`verified`	User has been verified
`rejected`	Verification was rejected

Idempotency

The idempotency-key header is required for user creation and must be a valid UUID. This prevents duplicate users if the request is retried.

Same idempotency key + same request body: Returns the existing user (200 OK)
Same idempotency key + different request body: Returns an error (409 Conflict)

Example

# First request - creates user
curl -X POST https://api.balampay.com/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "idempotency-key: 550e8400-e29b-41d4-a716-446655440001" \
  -d '{"type": "individual", "email": "[email protected]", ...}'

# Second request with same key and body - returns existing user
curl -X POST https://api.balampay.com/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "idempotency-key: 550e8400-e29b-41d4-a716-446655440001" \
  -d '{"type": "individual", "email": "[email protected]", ...}'

Error Responses

Missing Idempotency Key

Status: 400 Bad Request

{
  "error": "Invalid request data",
  "details": [
    {
      "path": "idempotency-key",
      "message": "Required",
      "code": "invalid_type"
    }
  ]
}

Invalid Idempotency Key Format

Status: 400 Bad Request

{
  "error": "Invalid request data",
  "details": [
    {
      "path": "idempotency-key",
      "message": "Invalid uuid",
      "code": "invalid_string"
    }
  ]
}

Idempotency Key Reused with Different Data

Status: 409 Conflict

{
  "code": "idempotency_key_reused",
  "message": "Idempotency key has already been used with different request data"
}

Validation Error

Status: 400 Bad Request

{
  "error": "Invalid request data",
  "details": [
    {
      "path": "first_name",
      "message": "Required",
      "code": "invalid_type"
    }
  ]
}

User Not Found

Status: 404 Not Found

{
  "code": "not_found",
  "message": "User with ID 550e8400-e29b-41d4-a716-446655440000 not found"
}

Unauthorized

Status: 401 Unauthorized

{
  "code": "unauthorized",
  "message": "No client ID found in claims"
}

Internal Server Error

Status: 500 Internal Server Error

{
  "code": "internal_error",
  "message": "An unexpected error occurred"
}

Best Practices

Generate unique UUIDs for idempotency keys - Use a UUID library to generate unique identifiers
Store the user ID - Save the returned user ID for future API calls
Validate data before sending - Ensure all required fields are provided and properly formatted
Use 3-letter ISO country codes - For nationality and address country fields (e.g., "USA", "MEX", "BRA")
Handle errors gracefully - Implement proper error handling for all possible error responses
Don't hardcode credentials - Store API keys and tokens securely using environment variables
Include all KYC fields upfront - Providing all required fields at user creation triggers automatic verification
Base64 encode documents properly - Use data URI format: data:image/jpeg;base64,...

Next Steps

After creating a user:

If verification_triggered: true:

Wait for the user.verification.accepted webhook notification
Once verified, create a virtual account for the user

If verification_triggered: false:

Either update the user with the missing required fields, or
Initiate identity verification manually (legacy flow)

Support

Email: [email protected]
Verification Guide: verification.md
Virtual Accounts: virtual-accounts.md