Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.killb.com/llms.txt

Use this file to discover all available pages before exploring further.

​
title: “Users” description: “Understanding user management and KYC in KillB”

​
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

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"
    }
  }
}

​
User Status

Users can have different statuses:
StatusDescriptionCan Transact?
ACTIVEUser is verified and approved✅ Yes
PENDINGVerification not completed yet❌ No
REJECTEDKYC verification failed❌ No
Gate all operations on status === ACTIVE. If a user is PENDING, send them to complianceUrl to complete verification.

​
Required Documents

​
Person Documents

  • 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

FieldTypeRequiredDescription
idUUIDAutoKillB-generated user ID
typeEnum✅PERSON or COMPANY
statusEnumAutoACTIVE, PENDING, REJECTED
customerIdUUIDAutoYour customer ID
externalIdStringOptionalYour system’s user ID
complianceUrlURLAutoKYC 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

  • 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
  • Always provide an externalId
  • Use your internal user ID
  • Enables easy lookups and reconciliation
  • Prevents duplicate user creation
  • Check status before allowing transactions
  • Guide users to next verification step
  • Monitor complianceUrl for KYC updates
  • Store KillB userId in your database
  • Map to your externalId
  • Cache user data appropriately
  • Sync status changes via webhooks

​
Common Questions

No. Each unique individual should have only one user profile. Use the same user ID for all their transactions.
  • L0-L1: Instant (automated)
  • L2: 1-24 hours (automated + manual review)
  • L3-L4: 1-5 business days (enhanced due diligence)
Yes, use the PATCH /api/v2/users/{id} endpoint. Some fields require re-verification.
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

API Reference

View the complete Users API documentation