Skip to main content
GET
/
v1
/
user
{
  "message": "Not authenticated"
}

​
Overview

Use this endpoint to retrieve complete profile information for the authenticated user. This endpoint is essential for:
  • Displaying user profile data in your application
  • Checking verification state before performing operations that require verified users
  • Validating user information before card orders or wallet operations
  • Syncing user data with your application’s database

​
Authentication

This endpoint requires both client authentication and user authentication:
​
x-client-key
string
required
Your client public key for API authentication
​
Authorization
string
required
Bearer token obtained from OAuth flow or login endpoint
​
x-us-env
boolean
default:"false"
Set to true to route requests to the US backend environment (if available for your client). Defaults to international environment.

​
Response

​
id
string
Unique identifier for the user (UUID format)
​
firstName
string
User’s first name
​
lastName
string
User’s last name
​
dateOfBirth
string
User’s date of birth in YYYY-MM-DD format
​
email
string
User’s email address
​
verificationState
string
Current verification status of the user. Possible values:
  • UNVERIFIED - User has not started verification
  • PENDING - Verification is in progress
  • VERIFIED - User is fully verified
  • REJECTED - Verification was rejected
​
phoneNumber
string
User’s phone number without country code
​
phoneCountryCode
string
Phone number country code (e.g., “+44”, “+1”)
​
addressLine1
string
Primary address line
​
addressLine2
string | null
Secondary address line (optional)
​
city
string
City of residence
​
zip
string
Postal/ZIP code
​
countryOfResidence
string
ISO 3166-1 alpha-2 country code of residence (e.g., “GB”, “US”)
​
countryOfNationality
string
ISO 3166-1 alpha-2 country code of nationality (e.g., “GB”, “US”)
​
usState
string | null
US state code (only for US residents, null otherwise)
​
ssn
string | null
Social Security Number (only for US residents, null otherwise)
​
createdAt
string
Timestamp when the user account was created (ISO 8601 format with timezone)

​
Examples

curl --request GET \
  --url https://dev.api.baanx.com/v1/user \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'x-client-key: YOUR_CLIENT_KEY'

​
Response Example

{
  "id": "100a99cf-f4d3-4fa1-9be9-2e9828b20ebb",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "2000-01-01",
  "email": "[email protected]",
  "verificationState": "VERIFIED",
  "phoneNumber": "7400846282",
  "phoneCountryCode": "+44",
  "addressLine1": "23 Werrington Bridge Rd",
  "addressLine2": "Milking Nook",
  "city": "Peterborough",
  "zip": "PE6 7PP",
  "countryOfResidence": "GB",
  "countryOfNationality": "GB",
  "usState": null,
  "ssn": null,
  "createdAt": "2023-03-27 17:07:12.662+03"
}

​
Error Responses

{
  "message": "Not authenticated"
}

​
401 Unauthorized

The access token is missing, invalid, or expired. You need to:
  • Ensure the Authorization header is present and properly formatted
  • Verify the access token hasn’t expired (6-hour lifetime)
  • Obtain a new access token using the refresh token if expired

​
403 Forbidden

The access token is valid but doesn’t have permission to access this resource. This may occur if:
  • The token doesn’t belong to a valid user
  • The client key doesn’t match the user’s associated client
  • The user account has been suspended or disabled

​
500 Internal Server Error

An unexpected error occurred on the server. If this persists:
  • Check the API status page
  • Contact support with the request timestamp
  • Implement retry logic with exponential backoff

​
Use Cases

​
Check Verification Status Before Card Order

Before allowing users to order a card, verify their verification state: 
async function canOrderCard(accessToken: string): Promise<boolean> {
  const response = await fetch('https://dev.api.baanx.com/v1/user', {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'x-client-key': 'YOUR_CLIENT_KEY'
    }
  });

  const user = await response.json();
  return user.verificationState === 'VERIFIED';
}

​
Display User Profile

Retrieve and display user information in your application: 
async function getUserProfile(accessToken: string) {
  const response = await fetch('https://dev.api.baanx.com/v1/user', {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'x-client-key': 'YOUR_CLIENT_KEY'
    }
  });

  if (!response.ok) {
    throw new Error('Failed to fetch user profile');
  }

  const user = await response.json();

  return {
    fullName: `${user.firstName} ${user.lastName}`,
    email: user.email,
    phone: `${user.phoneCountryCode}${user.phoneNumber}`,
    address: [
      user.addressLine1,
      user.addressLine2,
      user.city,
      user.zip
    ].filter(Boolean).join(', '),
    isVerified: user.verificationState === 'VERIFIED'
  };
}

​
Important Notes

Verification State: Most operations (card orders, wallet operations) require users to have VERIFIED status. Always check the verificationState field before allowing protected operations.
Sensitive Data: The response contains sensitive personal information including SSN (for US users). Ensure you:
  • Handle this data securely in your application
  • Never log sensitive fields
  • Comply with data protection regulations (GDPR, CCPA, etc.)
  • Only store what’s necessary for your use case
Caching: User profile data doesn’t change frequently. Consider implementing caching with appropriate TTL (5-15 minutes) to reduce API calls and improve performance.

​
Edge Cases & Limitations

​
Regional Variations

US Users: US-specific fields are populated: 
{
  "usState": "CA",
  "ssn": "***-**-1234"
}
International Users: US-specific fields are null: 
{
  "usState": null,
  "ssn": null
}

​
Verification States

User has registered but hasn’t started the verification process. They can:
  • Access their profile
  • Update basic information
  • View wallet balances
They cannot:
  • Order cards
  • Perform withdrawals
  • Access certain wallet features
Verification is in progress. The user should wait for verification to complete. Typical processing time is 5-30 minutes, but may take longer for manual review.
Full access to all platform features. This is the required state for most financial operations.
Verification failed. The user needs to:
  • Contact support to understand the rejection reason
  • Provide additional documentation if requested
  • Re-submit verification with corrected information
Rejected users cannot access protected features until successfully verified.

​
Optional Fields

The following fields may be null depending on user registration flow and region:
  • addressLine2 - Not required for all addresses
  • usState - Only populated for US residents
  • ssn - Only populated for US residents who provided SSN
Always check for null values before using these fields in your application.

​
Rate Limiting

This endpoint is subject to standard rate limits:
  • 1000 requests per minute per access token
  • 10000 requests per hour per client
If you exceed these limits, you’ll receive a 429 Too Many Requests response. Implement appropriate retry logic with exponential backoff.