Skip to main content

​
Overview

Before users can perform ramp transactions, they must be registered in KillB with appropriate KYC information. This guide covers creating both individual (PERSON) and business (COMPANY) users.
All users start at KYC level L0 or L1 and can be upgraded by submitting additional documentation.

​
Prerequisites

  • Valid access token from /api/v2/auth/login
  • User information to submit
  • Government ID details

​
Creating a Person User

​
Basic Example

POST /api/v2/users

{
  "type": "PERSON",
  "externalId": "user-12345",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "[email protected]",
    "phone": "+573001234567",
    "dateOfBirth": "1990-05-15",
    "address": {
      "street1": "Calle 123 #45-67",
      "city": "Bogotá",
      "state": "Cundinamarca",
      "zipCode": "110111",
      "countryCode": "CO"
    },
    "document": {
      "type": "NUIP",
      "number": "1234567890",
      "issuedCountryCode": "CO"
    }
  }
}

​
Required Fields

FieldTypeDescriptionExample
firstNamestringFirst name”Juan”
lastNamestringLast name”García”
emailstringEmail address”[email protected]”
phonestringPhone with country code”+573001234567”
dateOfBirthstringDate in YYYY-MM-DD”1990-05-15”
addressobjectPhysical addressSee below
documentobjectGovernment IDSee below

​
Address Object

{
  "street1": "Calle 123 #45-67",
  "street2": "Apt 301",
  "city": "Bogotá",
  "state": "Cundinamarca",
  "zipCode": "110111",
  "countryCode": "CO"
}
street2 is optional. Use for apartment numbers, building names, etc.

​
Document Object

Choose the appropriate document type for the user’s country: 
{
  "type": "NUIP",
  "number": "1234567890",
  "issuedCountryCode": "CO"
}
Supported Types:
  • NUIP - Número Único de Identificación Personal
  • PASSPORT - Passport
  • DRIVER_LICENSE - Driver’s License

​
Creating a Company User

For business entities: 
{
  "type": "COMPANY",
  "externalId": "company-456",
  "data": {
    "companyName": "Acme Technologies SAS",
    "tradeName": "Acme Tech",
    "registeredNumber": "900123456",
    "legalStructure": "LLC",
    "establishedOn": "2015-03-20",
    "phone": "+573001234567",
    "email": "[email protected]",
    "address": {
      "street1": "Carrera 7 #123-45",
      "city": "Bogotá",
      "state": "Cundinamarca",
      "zipCode": "110111",
      "countryCode": "CO"
    },
    "document": {
      "type": "NIT",
      "number": "900123456-1",
      "issuedCountryCode": "CO"
    },
    "mainOwnerUser": "owner-user-id",
    "ownerUsers": ["owner-1-id", "owner-2-id"]
  }
}

​
Company-Specific Fields

FieldRequiredDescription
companyName✅Legal registered name
tradeName❌Doing-business-as name
registeredNumber❌Business registration number
legalStructure❌LLC, C_CORP, S_CORP, etc.
establishedOn❌Company founding date
mainOwnerUser❌Primary owner user ID
ownerUsers❌Array of owner user IDs
naics❌Industry classification code
Company owners must be created as PERSON users first, then referenced in the company profile.

​
Optional Enhanced Fields

​
Investment Profile

Provide for higher KYC levels: 
{
  "investmentProfile": {
    "primarySourceOfFunds": "EMPLOYMENT",
    "primarySourceOfFundsDescription": "Software engineering salary",
    "totalAssets": "TEN_TO_100K",
    "usdValueOfFiat": "TEN_TO_100K",
    "monthlyDeposits": "UPTO_5",
    "monthlyWithdrawals": "UPTO_5",
    "monthlyInvestmentDeposit": "ONE_TO_100K",
    "monthlyInvestmentWithdrawal": "UPTO_1K"
  }
}
Source of Funds Options:
  • EMPLOYMENT - Salary/wages
  • SAVINGS - Personal savings
  • INVESTMENT - Investment returns
  • COMPANY - Business income
  • REAL_ESTATE - Property income
  • OTHER - Other sources

​
KYC Profile

Anti-money laundering information: 
{
  "kycProfile": {
    "fundsSendReceiveJurisdictions": ["CO", "US", "MX"],
    "engageInActivities": ["NONE"]
  }
}

​
Complete Code Examples

const createUser = async (userData) => {
  const response = await fetch('https://teste-94u93qnn.uc.gateway.dev/api/v2/users', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'PERSON',
      externalId: userData.id,
      data: {
        firstName: userData.firstName,
        lastName: userData.lastName,
        email: userData.email,
        phone: userData.phone,
        dateOfBirth: userData.dateOfBirth,
        address: {
          street1: userData.address.street,
          city: userData.address.city,
          state: userData.address.state,
          zipCode: userData.address.zipCode,
          countryCode: userData.address.country
        },
        document: {
          type: userData.document.type,
          number: userData.document.number,
          issuedCountryCode: userData.document.country
        }
      }
    })
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(`User creation failed: ${error.message}`);
  }
  
  const user = await response.json();
  
  // Store user ID in your database
  await db.users.update(userData.id, {
    killbUserId: user.id,
    kycLevel: user.accessLevel,
    kycStatus: user.status
  });
  
  return user;
};

​
Validation

Validate data before submission: 
const validateUserData = (data) => {
  const errors = [];
  
  // Email format
  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data.email)) {
    errors.push('Invalid email format');
  }
  
  // Phone format (E.164)
  if (!/^\+[1-9]\d{10,14}$/.test(data.phone)) {
    errors.push('Phone must be in format: +[country code][number]');
  }
  
  // Date of birth (18+ years)
  const dob = new Date(data.dateOfBirth);
  const age = (Date.now() - dob.getTime()) / (365.25 * 24 * 60 * 60 * 1000);
  if (age < 18) {
    errors.push('User must be 18 or older');
  }
  
  // Document number format
  if (data.document.type === 'NUIP' && !/^\d{10}$/.test(data.document.number)) {
    errors.push('NUIP must be 10 digits');
  }
  
  return errors;
};

​
Error Handling

Common user creation errors:
Error CodeDescriptionSolution
USER.0001User already existsUse existing user ID
USER.0002Invalid documentCheck document format
USER.0003Email already registeredUse different email
USER.0004Invalid phone formatUse E.164 format (+57…)
USER.0005Underage userUser must be 18+

​
Next Steps After Creation

1

Store User ID

Save the returned id in your database mapped to your externalId
2

Check KYC Status

Monitor status and accessLevel fields
3

Upload Documents

For L2+, upload ID images and additional docs
4

Create Accounts

Add bank accounts or wallets for this user

KYC Levels

Understanding KYC verification levels

Upload Documents

Submit ID images and proof documents

Manage Users

Query, update, and delete users

API Reference

Complete Users API documentation