curl --request POST \
  --url https://direct-pub-api.directgh.com/api/v1/external/users \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "otherName": "Michael",
  "mobileNumber": "+233241234567",
  "dateOfBirth": "1990-05-15",
  "ghanaCardNumber": "GHA-123456789-1",
  "monthlyIncome": 5000,
  "accountType": "MOMO",
  "accountNumber": "0241234567",
  "network": "MTN",
  "accountName": "John Doe"
}
'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "firstName": "John",
  "lastName": "Doe",
  "otherName": "Michael",
  "email": "john.doe@example.com",
  "mobileNumber": "+233241234567",
  "ghanaCardNumber": "GHA-123456789-1",
  "account": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "accountType": "MOMO",
    "accountNumber": "0241234567",
    "network": "MTN",
    "accountName": "John Doe",
    "createdAt": "2024-01-20T14:45:00Z"
  },
  "createdAt": "2024-01-20T14:45:00Z"
}

API Reference

Store User

Create a new institution member (user) programmatically. This endpoint allows you to register individual members with their personal information and optional account details.

User Creation:

If a user with the same mobile number already exists, they will be added to your institution
If the user doesn’t exist, a new user account will be created
The user will be automatically associated with your institution based on the API key
User information (date of birth) will be stored if provided

Account Details:

Account details are optional but can be provided for both Mobile Money (MOMO) and Bank accounts
For MOMO accounts, you must provide: accountType, accountNumber, network, and accountName
For Bank accounts, you must provide: accountType, accountNumber, bankName, and accountName
Valid account types: MOMO (Mobile Money) or BANK
Valid networks for MOMO: MTN, AIRTEL_TIGO, or TELECEL

Validation:

Email must be a valid email address
Mobile number must be a valid Ghanaian mobile number
Date of birth must be a valid date
Ghana Card number is required
Monthly income is required
If account details are provided, all required fields for that account type must be included

POST

external

users

curl --request POST \
  --url https://direct-pub-api.directgh.com/api/v1/external/users \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "otherName": "Michael",
  "mobileNumber": "+233241234567",
  "dateOfBirth": "1990-05-15",
  "ghanaCardNumber": "GHA-123456789-1",
  "monthlyIncome": 5000,
  "accountType": "MOMO",
  "accountNumber": "0241234567",
  "network": "MTN",
  "accountName": "John Doe"
}
'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "firstName": "John",
  "lastName": "Doe",
  "otherName": "Michael",
  "email": "john.doe@example.com",
  "mobileNumber": "+233241234567",
  "ghanaCardNumber": "GHA-123456789-1",
  "account": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "accountType": "MOMO",
    "accountNumber": "0241234567",
    "network": "MTN",
    "accountName": "John Doe",
    "createdAt": "2024-01-20T14:45:00Z"
  },
  "createdAt": "2024-01-20T14:45:00Z"
}

Authorizations

Authorization

string

header

required

HMAC signature authentication. The Authorization header must contain your public key and HMAC signature in the format: public_key:signature

Format: Authorization: public_key:signature

Example: Authorization: pub_abc123xyz:abc123def456ghi789...

The signature is generated by creating an HMAC hash of the request body (JSON stringified) using your secret key for POST/PUT requests. For GET requests, the signature is generated using the query parameters (JSON stringified) instead of the request body. Contact your account manager to obtain your public key and secret key for generating signatures.

Body

application/json

string<email>

required

User's email address

Example:

"john.doe@example.com"

firstName

string

required

User's first name

Example:

"John"

lastName

string

required

User's last name

Example:

"Doe"

mobileNumber

string

required

User's mobile phone number (must be a valid Ghanaian mobile number)

Example:

"+233241234567"

ghanaCardNumber

string

required

User's Ghana Card number

Example:

"GHA-123456789-1"

monthlyIncome

number<double>

required

User's monthly income

Example:

5000

otherName

string | null

User's middle name or other name (optional)

Example:

"Michael"

dateOfBirth

string<date> | null

User's date of birth (optional)

Example:

"1990-05-15"

accountType

enum<string> | null

Type of account (MOMO for Mobile Money, BANK for bank account). Required if account details are provided.

Available options:

MOMO,

BANK

Example:

"MOMO"

accountNumber

string | null

Account number. Required if accountType is provided.

Example:

"0241234567"

network

enum<string> | null

Mobile Money network. Required if accountType is MOMO.

Available options:

MTN,

AIRTEL_TIGO,

TELECEL

Example:

"MTN"

bankName

string | null

Bank name. Required if accountType is BANK.

Example:

"Ghana Commercial Bank"

accountName

string | null

Name on the account. Required if accountType is provided.

Example:

"John Doe"

Response

User created or added to institution successfully

User information

string<uuid>

Unique identifier of the user

Example:

"550e8400-e29b-41d4-a716-446655440000"

firstName

string

User's first name

Example:

"John"

lastName

string

User's last name

Example:

"Doe"

otherName

string | null

User's middle name or other name

Example:

"Michael"

string<email>

User's email address

Example:

"john.doe@example.com"

mobileNumber

string | null

User's mobile phone number

Example:

"+233241234567"

ghanaCardNumber

string | null

User's Ghana Card number

Example:

"GHA-123456789-1"

account

object

User's account details (Mobile Money or Bank account)

Show child attributes

createdAt

string<date-time> | null

Date and time when the user was created

Example:

"2024-01-15T10:30:00Z"

Fetch Users Update User

⌘I