Create & Update Account - Command by ClearGrid AI

Create or update accounts

curl --request POST \
  --url https://v3-api.cleargrid.ai/admin/v3/lenders/{lenderPublicId}/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accounts": [
    {
      "status": 1,
      "debtorCompanyId": "customer_001",
      "firstName": "Ahmed",
      "lastName": "Al Maktoum",
      "language": "en",
      "idNumber": "784-1990-1234567-1",
      "birthDate": "15/06/1990",
      "gender": "male",
      "nationality": "Emirati",
      "phones": [
        {
          "number": "+971501234567",
          "type": "mobile"
        }
      ],
      "emails": [
        {
          "email": "ahmed@example.com",
          "type": "personal"
        }
      ],
      "addresses": [
        {
          "street": "Sheikh Zayed Road",
          "city": "Dubai",
          "area": "Downtown",
          "country": "ARE",
          "type": "home"
        }
      ],
      "accountId": "ORD-2025-001",
      "subAccountId": "PMT-2025-001-01",
      "merchant": "TechStore UAE",
      "dateDue": "01/03/2026",
      "principal": "5000",
      "interest": "250",
      "fees": "50",
      "paidAmount": "0",
      "loanType": 4,
      "additionalData": {
        "productType": "Electronics"
      }
    }
  ]
}
'

{
  "code": 200,
  "message": "success",
  "body": "Processing started successfully",
  "errors": []
}

POST

admin

lenders

{lenderPublicId}

accounts

Create or update accounts

curl --request POST \
  --url https://v3-api.cleargrid.ai/admin/v3/lenders/{lenderPublicId}/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accounts": [
    {
      "status": 1,
      "debtorCompanyId": "customer_001",
      "firstName": "Ahmed",
      "lastName": "Al Maktoum",
      "language": "en",
      "idNumber": "784-1990-1234567-1",
      "birthDate": "15/06/1990",
      "gender": "male",
      "nationality": "Emirati",
      "phones": [
        {
          "number": "+971501234567",
          "type": "mobile"
        }
      ],
      "emails": [
        {
          "email": "ahmed@example.com",
          "type": "personal"
        }
      ],
      "addresses": [
        {
          "street": "Sheikh Zayed Road",
          "city": "Dubai",
          "area": "Downtown",
          "country": "ARE",
          "type": "home"
        }
      ],
      "accountId": "ORD-2025-001",
      "subAccountId": "PMT-2025-001-01",
      "merchant": "TechStore UAE",
      "dateDue": "01/03/2026",
      "principal": "5000",
      "interest": "250",
      "fees": "50",
      "paidAmount": "0",
      "loanType": 4,
      "additionalData": {
        "productType": "Electronics"
      }
    }
  ]
}
'

{
  "code": 200,
  "message": "success",
  "body": "Processing started successfully",
  "errors": []
}

This is the primary endpoint for managing accounts in Command. It supports creating new accounts, updating existing accounts (e.g., reflecting payments), and withdrawing accounts — all through a single unified request. Accounts are processed asynchronously in the background after the request is accepted.

Request

Endpoint

POST {{base_url}}/lenders/{{lenderPublicId}}/accounts

Environment	Base URL
Production	`https://v3-api.cleargrid.ai/admin/v3`
Staging	`https://stage-v3-api.cleargrid.ai/admin/v3`

Headers

Authorization

string

required

Bearer token obtained from the Lender Login endpoint. Format: Bearer <access_token>

Body Parameters

The request body contains an accounts array. Each item represents an account or sub-account to create, update, or withdraw.

accounts

array

required

An array of account objects. You can include multiple accounts and sub-accounts in a single request.

Show Account object fields

status

integer

required

The operation to perform on this account.

Value	Operation	Description
`1`	Create	Creates a new account/sub-account
`2`	Update	Updates an existing account/sub-account
`3`	Withdraw	Withdraws (cancels) an account/sub-account

debtorCompanyId

string

required

Unique identifier for the debtor/customer in your system.

firstName

string

required

The borrower’s first name.

lastName

string

required

The borrower’s last name.

language

string

required

Preferred language for communication. Use en for English, ar for Arabic.

idNumber

string

National identification number. For UAE, use the Emirates ID. For Saudi Arabia, use the National ID.

passportNumber

string

Borrower’s passport number.

birthDate

string

Date of birth in dd/MM/yyyy format.

gender

string

Borrower’s gender. Accepted values: male, female.

nationality

string

Borrower’s nationality.

phones

array

Array of phone number objects.

Show Phone object fields

number

string

required

The phone number.

type

string

The phone type. Examples: work, home, mobile.

emails

array

Array of email address objects.

Show Email object fields

string

required

The email address.

type

string

The email type. Examples: work, personal.

addresses

array

Array of address objects.

Show Address object fields

externalId

string

External UUID for the address in your system.

street

string

Street address.

city

string

City name.

area

string

Area or district.

zip

string

Postal / ZIP code.

country

string

Three-character country code (ISO 3166-1 alpha-3). Example: ARE for UAE, SAU for Saudi Arabia.

type

string

Address type. Examples: home, work, billing.

accountId

string

required

The main account identifier representing the primary contract with the debtor. All related sub-accounts are grouped under this ID.

subAccountId

string

required

A unique identifier for an individual obligation or installment under the main account. Each installment or fee is tracked as a distinct sub-account.

merchant

string

The merchant or business associated with the debt.

dateDue

string

The due date for this account/installment in dd/MM/yyyy format.

principal

string

required

The principal amount owed.

interest

string

The interest amount.

fees

string

Any additional fees.

paidAmount

string

The amount already paid by the borrower.

paidDate

string

The date of the last payment in dd/MM/yyyy format.

additionalData

object

A flexible key-value object for storing any additional metadata about the account. Common fields include productType, purpose, and other business-specific attributes.

loanType

integer

The type of loan or debt. Accepted values:

Value	Type
`1`	Credit Card
`2`	Lease
`3`	Personal Loan
`4`	BNPL (Buy Now Pay Later)
`5`	Car Rental
`6`	Subscription
`7`	Charge Back
`8`	Salary Advance Loan

Example Request

{
  "accounts": [
    {
      "status": 1,
      "debtorCompanyId": "customer_001",
      "firstName": "Ahmed",
      "lastName": "Al Maktoum",
      "language": "en",
      "idNumber": "784-1990-1234567-1",
      "passportNumber": "P1234567",
      "birthDate": "15/06/1990",
      "gender": "male",
      "nationality": "Emirati",
      "phones": [
        {
          "number": "+971501234567",
          "type": "mobile"
        }
      ],
      "emails": [
        {
          "email": "ahmed@example.com",
          "type": "personal"
        }
      ],
      "addresses": [
        {
          "externalId": "addr-uuid-001",
          "street": "Sheikh Zayed Road",
          "city": "Dubai",
          "area": "Downtown",
          "zip": "00000",
          "country": "ARE",
          "type": "home"
        }
      ],
      "accountId": "ORD-2025-001",
      "subAccountId": "PMT-2025-001-01",
      "merchant": "TechStore UAE",
      "dateDue": "01/03/2026",
      "principal": "5000",
      "interest": "250",
      "fees": "50",
      "paidAmount": "0",
      "paidDate": "",
      "additionalData": {
        "productType": "Electronics",
        "purpose": "Mobile phone purchase"
      },
      "loanType": 4
    },
    {
      "status": 1,
      "debtorCompanyId": "customer_001",
      "firstName": "Ahmed",
      "lastName": "Al Maktoum",
      "language": "en",
      "idNumber": "784-1990-1234567-1",
      "phones": [
        {
          "number": "+971501234567",
          "type": "mobile"
        }
      ],
      "emails": [
        {
          "email": "ahmed@example.com",
          "type": "personal"
        }
      ],
      "accountId": "ORD-2025-001",
      "subAccountId": "PMT-2025-001-02",
      "merchant": "TechStore UAE",
      "dateDue": "01/04/2026",
      "principal": "5000",
      "interest": "250",
      "fees": "50",
      "paidAmount": "0",
      "additionalData": {
        "productType": "Electronics"
      },
      "loanType": 4
    }
  ]
}

Understanding Accounts & Sub-Accounts

What is an accountId?

The accountId represents the main account or primary contract with a debtor. For example, a mobile phone purchase from an online store would be a single accountId. All related financial obligations (installments, fees) are grouped under this identifier.

What is a subAccountId?

The subAccountId represents an individual obligation or installment under the main account. Each installment or fee is tracked as a unique subAccountId, enabling itemized tracking of payments and dues. For example, a 4-installment BNPL plan would have 4 sub-accounts under one accountId.

How does the status field work?

The status field controls the operation:

Status	Operation	Use Case
`1`	Create	Onboarding a new account or sub-account
`2`	Update	Reflecting a payment, fee adjustment, or data correction
`3`	Withdraw	Removing or cancelling an account/sub-account

Example lifecycle:

Status 1: Create account with principal of 100, paidAmount of 0
Status 2: Update with paidAmount of 30 (balance becomes 70)
Status 2: Update with paidAmount of 50 (balance becomes 50)

Dynamic sub-account management

Sub-accounts are uniquely identified via subAccountId, which enables flexible real-time updates:

Add anytime — New sub-accounts (e.g., a new installment or charge) can be added independently at any time
Update anytime — Existing sub-accounts can be updated (e.g., fees change, payments received)
Withdraw anytime — A sub-account can be withdrawn (e.g., removed or marked as cancelled)
Automatic aggregation — Any operation on a sub-account automatically updates the main accountId aggregate (outstanding balance, status, etc.)

There is no requirement to submit all sub-accounts at once. The system is designed for incremental updates over time.

Important Notes

Date format: All dates must be in dd/MM/yyyy format (e.g., 15/03/2026).

Country codes: Use ISO 3166-1 alpha-3 three-character codes (e.g., ARE for UAE, SAU for Saudi Arabia, BHR for Bahrain).

Additional data: Any additional information about the debt or borrower that doesn’t fit into the standard fields should be placed in the additionalData object.

Response

200 — Success
400 — Validation Error
401 — Unauthorized
500 — Server Error

Data has been accepted and processing has started in the background.

{
  "code": 200,
  "message": "success",
  "body": "Processing started successfully",
  "errors": []
}

One or more accounts in the request failed validation. The errors array contains details for each failed account.

{
  "code": 400,
  "message": null,
  "body": "",
  "errors": [
    {
      "accountId": "ORD-2025-001",
      "errors": [
        "firstName is required",
        "principal must be a valid number"
      ]
    }
  ]
}

{
  "error": "Unauthorized"
}

The access token is missing, invalid, or expired. Re-authenticate using the Lender Login or Refresh Token endpoint.

{
  "error": "Something went wrong. Please try again later."
}

An unexpected server error occurred. If this persists, contact ClearGrid support.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

lenderPublicId

string

required

Lender public ID (UUID) returned by the Lender Login endpoint.

Body

application/json

accounts

object[]

required

Array of account objects to create, update, or withdraw.

Show child attributes

Response

Processing started successfully

code

integer

message

string | null

body

string

errors

object[]

Refresh Token Update Status

​Request

​Endpoint

​Headers

​Body Parameters

​Example Request

​Understanding Accounts & Sub-Accounts

​Important Notes

​Response

Authorizations

Path Parameters

Body

Response

Request

Endpoint

Headers

Body Parameters

Example Request

Understanding Accounts & Sub-Accounts

Important Notes

Response