Skip to main content
POST
Create Account

Overview

Creates a new user account with associated contact information and credentials. This is the first step in the merchant onboarding process.
Account approval required: New accounts require review and approval before they become active. Once approved, a merchant branch is created for the account.
Password security: Passwords expire after 90 days from creation. Credentials are stored securely.

Authentication

This endpoint requires JWT Bearer Token authentication.
See the Authentication Guide for details on generating JWT tokens.

Account Lifecycle

1

Create Account

Call this endpoint to create a new user account
2

Pending Approval

Account is created and awaits review and approval
3

Admin Review

Modulus Labs admin reviews and approves the account
4

Account Activation

Upon approval, a new merchant branch is created and assigned to the account
5

Begin Onboarding

Use the account ID to generate JWT token and proceed with merchant onboarding

Security Notes

  • Passwords are stored securely
  • Passwords expire after 90 days and must be changed
  • Never send passwords over unencrypted connections
  • Implement strong password requirements on the client side

Troubleshooting

Error: Username is not availableSolution:
  • Try a different username
  • Add numbers or special characters (dots, underscores, hyphens)
  • Consider using email prefix or unique identifiers
Error: user.password must have at least 1 uppercase and lowercase character, a number, and special characterSolution:
  • Ensure password is 8-22 characters long
  • Include at least one uppercase letter (A-Z)
  • Include at least one lowercase letter (a-z)
  • Include at least one number (0-9)
  • Include at least one special character from: #?!@$%^&*-
Example valid password: SecurePass123!

Next Steps

Generate JWT Token

Create a JWT Bearer Token for authentication

Onboard Merchant

Complete merchant onboarding with the account ID

Upload Documents

Upload required KYC documents

Error Handling

Learn about error codes and handling

Authorizations

Authorization
string
header
required

JWT Bearer token authentication

Body

application/json
contact
object
required

Contact information for the account

user
object
required

User credentials and personal information

Response

Account created successfully

id
integer
required

The new account id. Use it as the JWT sub for subsequent merchant-scoped calls and as merchantId for file upload.