Create & Update Account

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"
      }
    }
  ]
}
'

import requests

url = "https://v3-api.cleargrid.ai/admin/v3/lenders/{lenderPublicId}/accounts"

payload = { "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" }
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}
      }
    ]
  })
};

fetch('https://v3-api.cleargrid.ai/admin/v3/lenders/{lenderPublicId}/accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

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

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

{
  "error": "Unauthorized"
}

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"
      }
    }
  ]
}
'

import requests

url = "https://v3-api.cleargrid.ai/admin/v3/lenders/{lenderPublicId}/accounts"

payload = { "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" }
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'}
      }
    ]
  })
};

fetch('https://v3-api.cleargrid.ai/admin/v3/lenders/{lenderPublicId}/accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

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

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

{
  "error": "Unauthorized"
}

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

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.

array

required

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

Show Account object fields

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

string

required

Unique identifier for the debtor/customer in your system.

string

required

The borrower’s first name.

string

required

The borrower’s last name.

string

required

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

string

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

string

Borrower’s passport number.

string

Date of birth in dd/MM/yyyy format.

string

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

string

Borrower’s nationality.

array

Array of phone number objects.

Show Phone object fields

string

required

The phone number.

string

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

array

Array of email address objects.

Show Email object fields

string

required

The email address.

string

The email type. Examples: work, personal.

array

Array of address objects.

Show Address object fields

string

External UUID for the address in your system.

string

Street address.

string

City name.

string

Area or district.

string

Postal / ZIP code.

string

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

string

Address type. Examples: home, work, billing.

string

required

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

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.

string

The merchant or business associated with the debt.

string

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

string

required

The principal amount owed.

string

The interest amount.

string

Any additional fees.

string

The amount already paid by the borrower.

string

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

object

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

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[]

Getting Started

Authentication

Accounts

Exports

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

Authorizations

Path Parameters

Body

Response

Request

Endpoint

Headers

Body Parameters

Example Request

Understanding Accounts & Sub-Accounts

Important Notes

Response