Users

Endpoints for registration, query, and user management.

📝 User Registration
👤 Get Profile
✏️ Edit Profile
🔐 Change Password
🔑 Password Recovery

User Registration

Creates a new user account on the platform.

This endpoint only requires API Key, no prior authentication needed.

Endpoint

POST /user/

Headers

Content-Type: application/json
Accept: application/json
x-api-key: [API_KEY]

Request Body

Field	Type	Required	Description
`username`	string	✅	Must be valid email for PANEL/API
`email`	string	✅	Email address (converted to lowercase)
`password`	string	✅	Password (max 100 chars)
`phone`	string	✅	Phone number without country code
`country_code`	string	❌	Country code (e.g., `57` for Colombia)
`first_name`	string	❌	First name (max 100 chars)
`last_name`	string	❌	Last name (max 100 chars)

Field	Type	Required	Description
`document_type`	string	❌	Type: `CC`, `CE`, `NIT`, `PASSPORT`
`document_number`	string	❌	Document number
`type_person`	int	❌	`1` = NATURAL, `2` = JURIDICAL
`country_company_incorporation`	string	⚠️	Required if `type_person=2`
`gender`	string	❌	User gender
`date_birth`	string	❌	Birth date
`platform`	string	❌	`API`, `PANEL`, `IOS`, `ANDROID`
`referal_code`	string	❌	Referral code
`profile_picture`	string	❌	Profile picture URL

request.json

{
  "username": "user@example.com",
  "email": "user@example.com",
  "password": "Password123!",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "3001234567",
  "country_code": "57",
  "document_type": "CC",
  "document_number": "1234567890",
  "type_person": 1,
  "platform": "API"
}

curl -X POST https://dev.backend.colurs.co/user/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: [API_KEY]" \
  -d '{
    "username": "user@example.com",
    "email": "user@example.com",
    "password": "Password123!",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "3001234567",
    "country_code": "57",
    "document_type": "CC",
    "document_number": "1234567890",
    "type_person": 1,
    "platform": "API"
}'

Person Types

Value	Type	Description
`1`	NATURAL	Natural person
`2`	JURIDICAL	Juridical person (company)

⚠️

For juridical persons (type_person=2): The country_company_incorporation field is mandatory.

Fields for Juridical Person

If type_person=2, you can send legal representative data:

Field	Description
`document_type_legal`	Representative’s document type
`document_number_legal`	Representative’s document number
`name_legal`	Representative’s name
`last_name_legal`	Representative’s last name
`date_birth_legal`	Representative’s birth date
`gender_legal`	Representative’s gender

Validations

⚠️

The system validates for duplicates before creating the user.

✅ Unique email — No other user can have the same email
✅ Unique username — No other user can have the same username
✅ Unique phone — No other user can have the same phone
✅ Unique document — No other user can have the same document
✅ Username = Email — For PANEL and API platforms, username must be a valid email

Successful Response

201 CREATED

{
  "id": 123,
  "username": "user@example.com",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe"
}

Errors

Code	Error	Description
`400`	`InvalidReferrer`	Invalid referral code
`400`	`ProfileAlreadyReferred`	Profile already has a referral assigned
`404`	`ReferalCodeNotExist`	Referral code doesn’t exist
`400`	`TypePersonRequired`	Person type required
`400`	`InfoBusinessDoesNotExist`	Business info doesn’t exist
`400`	`IntegrationException`	External integration error

Get Profile

Gets the authenticated user’s profile information.

Endpoint

GET /user/

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]

Query Parameters

Parameter	Type	Description
`lite`	boolean	Returns reduced version of profile

Response

GET /user/

{
  "id": 123,
  "uuid": "abc-123-def-456",
  "username": "user@example.com",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "alias": "jdoe",
  "phone": "3001234567",
  "country": "CO",
  "country_code": "57",
  "city": "Bogotá",
  "address": "Street 123 #45-67",
  "document_type": "CC",
  "document_number": "1234567890",
  "phone_verified": true,
  "email_verified": true,
  "type_person": "NATURAL",
  "level": 5,
  "document_status": "APPROVED",
  "has_pin": true,
  "has_otp": false,
  "roles": ["user"],
  "last_login": "2024-01-15T10:30:00Z",
  "platform": "API"
}

GET /user/?lite=true

{
  "id": 123,
  "username": "user@example.com",
  "email": "user@example.com",
  "phone_verified": true,
  "email_verified": true,
  "level": 5
}

Basic Data:

id, uuid, username, email
first_name, last_name, alias, url
phone, country_code, country, city, address
document_type, document_number
gender, date_birth, date_expiration
profile_picture

Status:

phone_verified, email_verified
type_person (NATURAL/JURIDICAL)
level, document_status
has_pin, has_otp
platform, last_login, ip

Fees and Limits:

fee_iva, fee_pse, withdraw_fee
fee_payment, fee_withdraw, fee_reload, fee_send
fee_efecty, fee_baloto
reload_tier_1, reload_tier_2, reload_tier_3, reload_tier_4
min_transaction_quantity, max_transaction_quantity
min_reload_quantity, max_reload_quantity
balance_limit, amount_balance_limit

Configuration:

payment_methods_configuration
roles (user groups)
onboarding (process status)
country_company_incorporation
wallet_info_enabled
has_uma_profile
show_referral_panel
merchant_id, is_merchant

Profile Fields

Field	Type	Description
`id`	int	Unique profile ID
`uuid`	string	Universal UUID
`username`	string	Username (email)
`email`	string	Email address
`first_name`	string	First name
`last_name`	string	Last name
`phone`	string	Phone
`country_code`	string	Country code
`phone_verified`	boolean	Is phone verified?
`email_verified`	boolean	Is email verified?
`type_person`	string	`NATURAL` or `JURIDICAL`
`level`	int	Validation level (0-5)
`has_pin`	boolean	Has PIN configured?
`has_otp`	boolean	Has 2FA enabled?
`is_merchant`	boolean	Is merchant?

Edit Profile

Updates the authenticated user’s profile information.

Endpoint

POST /edit_profile/

Headers

Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json
x-api-key: [API_KEY]

Editable Fields

Edit personal data

{
  "first_name": "John Carlos",
  "last_name": "Doe Smith",
  "alias": "jcdoe",
  "phone": "3009876543",
  "gender": "M",
  "date_birth": "1990-01-15",
  "date_expiration": "2030-01-15",
  "profile_picture": "https://example.com/photo.jpg"
}

Edit location

{
  "country": "CO",
  "city": "Medellín",
  "address": "Avenue 50 #10-20"
}

Edit VAT

{
  "fee_iva": 19.0
}

This creates or updates a CustomConfiguration for the profile.

Configure payment methods

{
  "payment_methods_configuration": {
    "pse": true,
    "nequi": true,
    "bancolombia": true,
    "efecty": false
  }
}

Configure reload methods

{
  "payment_methods_configuration_reload": {
    "bancolombia": true,
    "pse": true,
    "nequi": false
  }
}

Apply Referral Code

Apply referral code

{
  "referal_code": "ABC123"
}

🎁

When applying a valid referral code, the following are automatically updated:

max_transaction_quantity
payment_methods_configuration
payment_methods_configuration_reload

Successful Response

200 OK

{
  "message": "Profile edited successfully"
}

Or for specific configurations:

200 OK

{
  "result": "ok"
}

Errors

Code	Error	Description
`404`	`UNABLE_TO_GET_PROFILE`	Profile not found
`400`	`UserToEditExist`	User to edit already exists
`400`	`UserByEmail`	Email already in use by another user
`400`	`UserByPhoneExist`	Phone already in use by another user

Change Password

Updates the authenticated user’s password.

🔒

For security, the current password is required and the new password must be confirmed.

Endpoint

PUT /profile/change-password

Headers

Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json
x-api-key: [API_KEY]

Request

request.json

{
  "old_password": "CurrentPassword123",
  "new_password": "NewPassword456!",
  "new_password_confirmation": "NewPassword456!"
}

Field	Type	Required	Description
`old_password`	string	✅	Current password
`new_password`	string	✅	New password
`new_password_confirmation`	string	✅	New password confirmation

Validations

✅ Current password must be correct
✅ new_password must equal new_password_confirmation
✅ Rate limiting implemented to prevent brute force attacks

Response

200 OK

{
  "message": "Password updates successfully."
}

Errors

Code	Error	Description
`429`	`PasswordInTimeout`	Too many attempts, wait before retrying
`400`	`PasswordNotMatch`	Current password incorrect

Password Recovery

Process to recover access when the user forgot their password.

This endpoint only requires API Key, no authentication needed.

Endpoint - Request Recovery

POST /password_recovery_request/

Headers

Content-Type: application/json
x-api-key: [API_KEY]

Request

request.json

{
  "email": "user@example.com"
}

Recovery Flow

Step 1: Request recovery

User sends their email to /password_recovery_request/ endpoint.

Step 2: Receive code

System sends a verification code to user’s email.

Step 3: Validate code

User enters the received code to validate their identity.

Step 4: Set new password

User can set a new password.

Validation Levels

The system handles different identity verification levels:

📊

The level determines what operations the user can perform.

Level	Status	Description
`0`	🔴 Unvalidated	Newly created user
`1`	🟡 Pending	Documents submitted, under review
`2`	🟠 With errors	Documents rejected
`5`	🟢 Validated	Verification complete

Level 0 - Unvalidated

New user, can only view their profile. Cannot perform transactions.

Level 1 - Pending

Documents submitted, awaiting compliance team approval.

Level 2 - With errors

Documents rejected for some reason. User must resubmit documentation.

Level 5 - Fully validated

Full access to all platform functionalities.

Collaborators

If the user is a collaborator (not a regular profile), the GET /user/ response returns data from ColaboratorSerializer instead of ProfileSerializer.

👥

Collaborators are users with special roles that belong to an organization.

Authentication Verification

Users

Quick Navigation

User Registration

Endpoint

Headers

Request Body

Person Types

Fields for Juridical Person

Validations

Successful Response

Errors

Get Profile

Endpoint

Headers

Query Parameters

Response

Profile Fields

Edit Profile

Endpoint

Headers

Editable Fields

Apply Referral Code

Successful Response

Errors

Change Password

Endpoint

Headers

Request

Validations

Response

Errors

Password Recovery

Endpoint - Request Recovery

Headers

Request

Recovery Flow

Step 1: Request recovery

Step 2: Receive code

Step 3: Validate code

Step 4: Set new password

Validation Levels

Level 0 - Unvalidated

Level 1 - Pending

Level 2 - With errors

Level 5 - Fully validated

Collaborators