Skip to main content
The User Service is the identity backbone of the PCX platform. It owns every user record from initial sign-up through KYC approval and ongoing lifecycle management.

​
What it does

Registration & confirmation — Users register via Cognito (POST /users/register). Cognito sends a verification email; the user confirms with a code (POST /users/confirm). An optional org_name or org_id wires the user into an organization at the same time. Profile management — Standard CRUD for user records. Mutable fields (name, phone, address, ID documents) are updated via PUT /users/{user_id}. Role and status changes go through dedicated endpoints so they can be audited separately. KYC lifecycle — The service integrates with two KYC providers:
  • Veriff (or equivalent) — webhook callback at POST /users/webhook-kyc updates status after a session completes.
  • Bridge — POST /users/{user_id}/bridge-kyc creates a Bridge customer and returns a terms-of-service link; Bridge status transitions arrive at POST /users/webhook/kyc.
Verification data requests — For Nigeria-specific compliance (BVN/NIN), a sub-system tracks requests sent to users and beneficiaries. Admins trigger notifications (POST /users/notifications/verification-request), users submit their numbers (POST /users/verification-requests/submit), and the lifecycle is tracked in VerificationRequest records. Notifications — Internal systems call POST /users/notifications/kyc to push KYC status updates to users via email, SMS, and push channels through the notifications Lambda. Analytics — Nine admin-only analytics endpoints give visibility into active user counts, growth trends, KYC funnel progression, status/role distributions, transaction averages, and geographic spread.

​
Key concepts

ConceptDescription
UserStatusnot_verified → pending_verification → active or rejected. Also pending, sandbox, inactive.
UserRoleretail, freelancer, org-staff, admin, super-admin.
UserTypeuser, staff, merchant, org-admin, internal-admin.
IDTypepassport, drivers_license, national_id, other.
VerificationRequestTracks a BVN/NIN request from creation through submission and verification.

​
Authentication

All endpoints except POST /users/register and POST /users/confirm require a valid Bearer token. Analytics endpoints and admin status-change endpoints additionally enforce the internal-admin role via the roles_required middleware.