Users

What is a User?

A User in KillB represents an individual or business entity that can perform ramp transactions. Users are required to complete Know Your Customer (KYC) or Know Your Business (KYB) verification before transacting.

Every transaction in KillB must be associated with a verified user to comply with regulatory requirements.

User Types

PERSON
COMPANY

Individual users (natural persons)Required Information:

Full name (first, middle, last)
Date of birth
Email and phone
Physical address
Government-issued ID
Nationality and citizenship

Use Cases:

Personal remittances
Individual investments
Personal crypto purchases

Example:

{
  "type": "PERSON",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "dateOfBirth": "1990-05-15",
    "email": "[email protected]",
    "phone": "+573001234567",
    "document": {
      "type": "NUIP",
      "number": "1234567890",
      "issuedCountryCode": "CO"
    }
  }
}

Business entities and corporationsRequired Information:

Company name and trade name
Registration number
Legal structure
Business address
Tax ID (NIT, EIN, RFC, etc.)
Owner information

Use Cases:

Business payments
Corporate treasury
B2B transactions
Payroll services

Example:

{
  "type": "COMPANY",
  "data": {
    "companyName": "Acme Corp SAS",
    "tradeName": "Acme",
    "registeredNumber": "900123456",
    "legalStructure": "LLC",
    "email": "[email protected]",
    "document": {
      "type": "NIT",
      "number": "900123456-1",
      "issuedCountryCode": "CO"
    }
  }
}

KYC Levels

KillB implements a tiered KYC system (L0-L4) that determines transaction limits:

L0 - Email Verification

Requirements:

Email address only
Email verification

Limits:

Daily: $500
Monthly: $1,000

Best For:

Initial testing
Small transactions
New user onboarding

L1 - Basic KYC

Requirements:

Full name
Date of birth
Government ID number
Phone number
Address

Limits:

Daily: $2,500
Monthly: $10,000

Best For:

Regular users
Standard transactions
Most common use case

L2 - Enhanced KYC

Requirements:

All L1 requirements
ID document images (front/back)
Proof of address
Selfie verification

Limits:

Daily: $10,000
Monthly: $50,000

Best For:

Power users
Frequent traders
Higher value transactions

L3 - Advanced KYC

Requirements:

All L2 requirements
Source of funds documentation
Bank statements
Enhanced due diligence

Limits:

Daily: $50,000
Monthly: $250,000

Best For:

High net worth individuals
Business accounts
Large transactions

L4 - Enterprise

Requirements:

Custom verification
Business licenses
Corporate documents
Compliance review

Limits:

Custom limits
Negotiated rates

Best For:

Institutional clients
High-volume operations
White-label integrations

User Lifecycle

User Status

Users can have different statuses:

Status	Description	Can Transact?
`ACTIVE`	User is verified and approved	✅ Yes
`PENDING`	KYC documents under review	❌ No
`REJECTED`	KYC verification failed	❌ No

Required Documents

Person Documents

Colombia
Mexico
United States
Other Countries

NUIP (Número Único de Identificación Personal)
Cédula de Ciudadanía (CC)
Passport
Driver’s License

Company Documents

NIT (Colombia) - Tax identification number
RFC (Mexico) - Federal taxpayer registry
EIN (USA) - Employer identification number
CNPJ (Brazil) - National registry of legal entities
CUIT (Argentina) - Unique tax identification code

External ID

The externalId field allows you to link KillB users to your own user system:

{
  "type": "PERSON",
  "externalId": "user_abc123_from_my_system",
  "data": { ... }
}

Benefits:

Map KillB users to your database
Avoid duplicate user creation
Simplify user lookups
Maintain referential integrity

Use your internal user ID as the externalId for easy mapping between systems.

User Properties

Core Fields

Field	Type	Required	Description
`id`	UUID	Auto	KillB-generated user ID
`type`	Enum	✅	PERSON or COMPANY
`status`	Enum	Auto	ACTIVE, PENDING, REJECTED
`accessLevel`	Enum	Auto	L0, L1, L2, L3, L4
`customerId`	UUID	Auto	Your customer ID
`externalId`	String	Optional	Your system’s user ID
`complianceUrl`	URL	Auto	KYC verification portal

Person-Specific Fields

firstName, middleName, lastName
dateOfBirth
nationality, citizenship
employmentStatus, occupation
employerName, employmentDescription

Company-Specific Fields

companyName, tradeName
registeredNumber
legalStructure (LLC, C_CORP, S_CORP, etc.)
establishedOn
naics, naicsDescription
mainOwnerUser, ownerUsers[]

Investment Profile

Users must provide an investment profile for compliance:

{
  "investmentProfile": {
    "primarySourceOfFunds": "EMPLOYMENT",
    "primarySourceOfFundsDescription": "Software engineer salary",
    "totalAssets": "TEN_TO_100K",
    "usdValueOfFiat": "TEN_TO_100K",
    "monthlyDeposits": "UPTO_5",
    "monthlyWithdrawals": "UPTO_5",
    "monthlyInvestmentDeposit": "ONE_TO_100K",
    "monthlyInvestmentWithdrawal": "UPTO_1K",
    "usdValueOfCrypto": "TEN_TO_100K",
    "monthlyCryptoDeposits": "UPTO_5",
    "monthlyCryptoWithdrawals": "UPTO_5"
  }
}

Source of Funds Options

EMPLOYMENT - Salary/wages
SAVINGS - Personal savings
INVESTMENT - Investment income
COMPANY - Business revenue
REAL_ESTATE - Property income
TRUST - Trust fund
OTHER - Other sources

KYC Profile

Anti-money laundering and compliance information:

{
  "kycProfile": {
    "fundsSendReceiveJurisdictions": ["CO", "US", "MX"],
    "engageInActivities": ["NONE"]
  }
}

Prohibited Activities

Users must confirm they don’t engage in:

ADULT_ENTERTAINMENT
DRUGS
FIREARMS
GAMBLING
MARIJUANA
TUMBLING (Crypto mixing)

Managing Users

Create a User

POST /api/v2/users

See Create User Guide for detailed examples.

Query Users

GET /api/v2/users?type=PERSON&email=[email protected]

Filter Options:

type - PERSON or COMPANY
firstName, lastName, email
externalId - Your system ID
customerId - Filter by customer

Update User

PATCH /api/v2/users/{userId}

Update user information, upload additional documents, or modify profile data.

Delete User

DELETE /api/v2/users/{userId}

User deletion is a soft delete. User data is retained for compliance but marked as inactive.

Best Practices

Collect Accurate Information

Validate data formats before submission
Ensure names match government IDs exactly
Use correct phone number format (+[country code][number])
Verify email addresses
Confirm addresses are complete and accurate

Use External IDs

Always provide an externalId
Use your internal user ID
Enables easy lookups and reconciliation
Prevents duplicate user creation

Handle KYC States

Check status before allowing transactions
Show users their accessLevel and limits
Guide users to next verification step
Monitor complianceUrl for KYC updates

Store User IDs

Store KillB userId in your database
Map to your externalId
Cache user data appropriately
Sync status changes via webhooks

Common Questions

Can one person have multiple user profiles?

No. Each unique individual should have only one user profile. Use the same user ID for all their transactions.

How long does KYC verification take?

L0-L1: Instant (automated)
L2: 1-24 hours (automated + manual review)
L3-L4: 1-5 business days (enhanced due diligence)

Can I update user information after creation?

Yes, use the PATCH /api/v2/users/{id} endpoint. Some fields require re-verification.

What happens if KYC is rejected?

The user status becomes REJECTED and they cannot transact. Check the note field for rejection reasons. Users can resubmit corrected information.

Next Steps

Create Your First User

Follow step-by-step guide to create users

Understanding Accounts

Learn about bank accounts and wallets

KYC Levels Deep Dive

Detailed guide on KYC requirements

API Reference

View the complete Users API documentation

Get Started

Core Concepts

Users & KYC

Accounts

Pre-Funded Accounts

On/Off Ramps

Savings & Custodial

Webhooks

Resources

What is a User?

User Types

KYC Levels

User Lifecycle

User Status

Required Documents

Person Documents

Company Documents

External ID

User Properties

Core Fields

Person-Specific Fields

Company-Specific Fields

Investment Profile

Source of Funds Options

KYC Profile

Prohibited Activities

Managing Users

Create a User

Query Users

Update User

Delete User

Best Practices

Common Questions

Next Steps

Create Your First User

Understanding Accounts

KYC Levels Deep Dive

API Reference

Get Started

Core Concepts

Users & KYC

Accounts

Pre-Funded Accounts

On/Off Ramps

Savings & Custodial

Webhooks

Resources

​What is a User?

​User Types

​KYC Levels

​User Lifecycle

​User Status

​Required Documents

​Person Documents

​Company Documents

​External ID

​User Properties

​Core Fields

​Person-Specific Fields

​Company-Specific Fields

​Investment Profile

​Source of Funds Options

​KYC Profile

​Prohibited Activities

​Managing Users

​Create a User

​Query Users

​Update User

​Delete User

​Best Practices

​Common Questions

​Next Steps

Create Your First User

Understanding Accounts

KYC Levels Deep Dive

API Reference

What is a User?

User Types

KYC Levels

User Lifecycle

User Status

Required Documents

Person Documents

Company Documents

External ID

User Properties

Core Fields

Person-Specific Fields

Company-Specific Fields

Investment Profile

Source of Funds Options

KYC Profile

Prohibited Activities

Managing Users

Create a User

Query Users

Update User

Delete User

Best Practices

Common Questions

Next Steps