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.

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

Request Body - Individual User

{
  "type": "individual",
  "email": "[email protected]",
  "phone": "+1234567890",
  "first_name": "John",
  "last_name": "Doe",
  "middle_name": "William",
  "birth_date": "1990-01-15",
  "nationality": "USA",
  "residential_address": {
    "street_line_1": "123 Main St",
    "street_line_2": "Apt 4B",
    "city": "San Francisco",
    "subdivision": "CA",
    "postal_code": "94105",
    "country": "USA"
  },
  "metadata": {
    "custom_field": "custom_value"
  }
}

Request Body - Business User

{
  "type": "business",
  "email": "[email protected]",
  "business_legal_name": "Acme Corporation",
  "business_trade_name": "Acme",
  "registered_address": {
    "street_line_1": "123 Business Ave",
    "city": "San Francisco",
    "subdivision": "CA",
    "postal_code": "94105",
    "country": "USA"
  },
  "metadata": {
    "custom_field": "custom_value"
  }
}

Field Descriptions - Individual User

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)
`birth_date`	string	No	Date of birth in YYYY-MM-DD format
`nationality`	string	No	3-letter ISO country code (e.g., "USA")
`residential_address`	object	No	User's residential address
`residential_address.street_line_1`	string	No	Street address
`residential_address.street_line_2`	string	No	Apartment, suite, etc.
`residential_address.city`	string	No	City
`residential_address.subdivision`	string	No	State or province
`residential_address.postal_code`	string	No	ZIP or postal code
`residential_address.country`	string	No	3-letter ISO country code
`status`	string	No	User status: `"active"`, `"inactive"`, or `"suspended"` (default: `"active"`)
`metadata`	object	No	Custom key-value pairs for your reference

Field Descriptions - Business User

Field	Type	Required	Description
`type`	string	Yes	Must be `"business"`
`email`	string	Yes	Valid email address
`business_legal_name`	string	Yes	Legal business name
`business_trade_name`	string	No	Trade or DBA name
`registered_address`	object	No	Business registered address
`registered_address.street_line_1`	string	No	Street address
`registered_address.street_line_2`	string	No	Suite, floor, etc.
`registered_address.city`	string	No	City
`registered_address.subdivision`	string	No	State or province
`registered_address.postal_code`	string	No	ZIP or postal code
`registered_address.country`	string	No	3-letter ISO country code
`status`	string	No	User status: `"active"`, `"inactive"`, or `"suspended"` (default: `"active"`)
`metadata`	object	No	Custom key-value pairs for your reference

Example Request

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",
    "email": "[email protected]",
    "phone": "+12025551234",
    "first_name": "John",
    "last_name": "Doe",
    "birth_date": "1990-01-15",
    "nationality": "USA",
    "residential_address": {
      "street_line_1": "123 Main St",
      "city": "San Francisco",
      "subdivision": "CA",
      "postal_code": "94105",
      "country": "USA"
    }
  }'

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "individual",
  "email": "[email protected]",
  "phone": "+12025551234",
  "first_name": "John",
  "last_name": "Doe",
  "middle_name": "",
  "birth_date": "1990-01-15",
  "nationality": "USA",
  "residential_address": {
    "street_line_1": "123 Main St",
    "street_line_2": "",
    "city": "San Francisco",
    "subdivision": "CA",
    "postal_code": "94105",
    "country": "USA"
  },
  "status": "active",
  "verification_status": "unverified",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "metadata": {}
}

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]",
  "phone": "+12025551234",
  "first_name": "John",
  "last_name": "Doe",
  "birth_date": "1990-01-15",
  "nationality": "USA",
  "residential_address": {
    "street_line_1": "123 Main St",
    "street_line_2": "",
    "city": "San Francisco",
    "subdivision": "CA",
    "postal_code": "94105",
    "country": "USA"
  },
  "verification_status": "verified",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "metadata": {}
}

User Status

Status	Description
`active`	User is active and can create virtual accounts
`inactive`	User account is temporarily disabled

Note: suspended status exists internally but is not exposed via the API.

Verification Status

Status	Description
`unverified`	User has not completed identity verification
`verified`	User has successfully completed identity verification
`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")
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

Next Steps

After creating a user:

Initiate identity verification to enable virtual account creation
Once verified, create a virtual account for the user

Support

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