Skip to main content

​
Querying Users

​
Get All Users

GET /api/v2/users?type=PERSON
Filter Parameters:
  • type - PERSON or COMPANY
  • id - Specific user ID
  • externalId - Your system’s user ID
  • firstName, lastName - Name search
  • email - Email search
  • customerId - Filter by customer
  • limit, page - Pagination
Example: 
curl --request GET \
  --url 'https://teste-94u93qnn.uc.gateway.dev/api/v2/users?type=PERSON&limit=10&page=1' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Response: 
{
  "users": [
    {
      "id": "user-1",
      "type": "PERSON",
      "status": "ACTIVE",
      "accessLevel": "L2",
      "data": { /* user data */ }
    }
  ],
  "totalPage": 5
}

​
Get User by ID

GET /api/v2/users/{userId}

const getUser = async (userId) => {
  const response = await fetch(
    `https://teste-94u93qnn.uc.gateway.dev/api/v2/users/${userId}`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );
  
  return await response.json();
};

​
Find by External ID

GET /api/v2/users?externalId=user-12345
Use externalId to quickly find users by your internal user ID without storing KillB’s user ID everywhere.

​
Updating Users

PATCH /api/v2/users/{userId}
Update user information after creation: 
{
  "type": "PERSON",
  "data": {
    "email": "[email protected]",
    "phone": "+573009876543",
    "address": {
      "street1": "New Street 456",
      "city": "Medellín",
      "state": "Antioquia",
      "zipCode": "050001",
      "countryCode": "CO"
    }
  }
}
Updatable Fields:
  • Email
  • Phone number
  • Address
  • Employment information
  • Investment profile
  • KYC profile
Changing certain fields (like document number) may trigger re-verification and temporarily set status to PENDING.

​
Deleting Users

DELETE /api/v2/users/{userId}

const deleteUser = async (userId) => {
  const response = await fetch(
    `https://teste-94u93qnn.uc.gateway.dev/api/v2/users/${userId}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );
  
  if (response.ok) {
    console.log('User deleted successfully');
  }
};
User deletion is a soft delete. User data is retained for compliance but marked as inactive. Users with pending ramps cannot be deleted.

​
User Status Management

Monitor and handle different user statuses: 
const handleUserStatus = (user) => {
  switch(user.status) {
    case 'ACTIVE':
      // User can transact
      return { canTransact: true, message: 'Ready to transact' };
      
    case 'PENDING':
      // KYC under review
      return {
        canTransact: false,
        message: 'KYC verification in progress',
        action: `Complete verification at ${user.complianceUrl}`
      };
      
    case 'REJECTED':
      // KYC rejected
      return {
        canTransact: false,
        message: 'Verification failed',
        reason: user.note,
        action: 'Please resubmit documents'
      };
      
    default:
      return { canTransact: false };
  }
};

​
Bulk Operations

​
Get Multiple Users

const getUsersByExternalIds = async (externalIds) => {
  const users = await Promise.all(
    externalIds.map(externalId =>
      fetch(`/api/v2/users?externalId=${externalId}`, {
        headers: { 'Authorization': `Bearer ${token}` }
      }).then(r => r.json())
    )
  );
  
  return users.flat(2); // Flatten nested arrays
};

​
Batch User Creation

const createMultipleUsers = async (usersData) => {
  const results = {
    successful: [],
    failed: []
  };
  
  for (const userData of usersData) {
    try {
      const user = await createUser(userData);
      results.successful.push(user);
    } catch (error) {
      results.failed.push({
        externalId: userData.externalId,
        error: error.message
      });
    }
  }
  
  return results;
};

​
Syncing User Data

Keep user data synchronized between your system and KillB: 
const syncUser = async (localUserId) => {
  // Get user from your database
  const localUser = await db.users.findById(localUserId);
  
  if (!localUser.killbUserId) {
    // Create in KillB
    const killbUser = await createUser(localUser);
    await db.users.update(localUserId, {
      killbUserId: killbUser.id
    });
    return killbUser;
  }
  
  // Get current status from KillB
  const killbUser = await getUser(localUser.killbUserId);
  
  // Update local database
  await db.users.update(localUserId, {
    kycStatus: killbUser.status,
    kycLevel: killbUser.accessLevel
  });
  
  return killbUser;
};

​
Webhook Integration

Use webhooks to stay updated: 
app.post('/webhooks/killb', (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'user.updated') {
    // Update local database
    db.users.updateByKillbId(data.id, {
      kycStatus: data.status,
      kycLevel: data.accessLevel,
      updatedAt: new Date()
    });
  }
  
  res.status(200).json({ received: true });
});

​
Best Practices

Always provide externalId when creating users:
{
  "externalId": yourSystemUserId,
  "data": { /* user info */ }
}
This allows easy lookups without storing KillB IDs everywhere.
Store frequently accessed data locally:
const getUserWithCache = async (userId) => {
  const cached = await cache.get(`user:${userId}`);
  if (cached) return cached;
  
  const user = await getUser(userId);
  await cache.set(`user:${userId}`, user, 3600); // 1 hour
  return user;
};
Not all fields can be updated. Handle errors:
try {
  await updateUser(userId, updates);
} catch (error) {
  if (error.code === 'USER.0006') {
    // Field not updatable
    console.log('Cannot update this field');
  }
}

​
Next Steps

Create Accounts

Add bank accounts and wallets for users

Start Transactions

Begin processing ramp transactions