Send Accounts

📂 Accounts API

Endpoint

POST {api_base_url}/lenders/{lenderPublicId}/accounts

• Prod: https://api.cleargrid.ae/api/v1/lenders/{lenderPublicId}/accounts

• Dev: https://api-dev.cleargrid.ae/api/v1/lenders/{lenderPublicId}/accounts

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Example Request

{
{
    "accounts": [
        {
            "status": 1,
            "debtorCompanyId": "debtor_company_id",
            "firstName": "first_name",
            "lastName": "last_name",
            "language": "en",
            "idNumber": "emirates_id/Saudi NationalId",
            "passportNumber": "passport_number",
            "birthDate": "birth_date",
            "gender": "male",
            "nationality": "",
            "phones": [
                {
                    "number": "*********",
                    "type": "work"
                }
            ],
            "emails": [
                {
                    "email": "[email protected]",
                    "type": null
                }
            ],
            "addresses": [
                {
                    "externalId": "external_uuid",
                    "street": null,
                    "city": null,
                    "area": null,
                    "zip": null,
                    "country": "three_characters_country", // eg UAE
                    "type": null
                }
            ],
            "accountId": "unique_account_id",
            "subAccountId": "unique_sub_account_id_1",
            "merchant": "merchant",
            "dateDue": "due_date",
            "principal": "principal_amount",
            "interest": "interest_amount",
            "fees": "fees",
            "paidAmount": "paid_amount",
            "paidDate": "paid_date",
            "additionalData": {
                "productType": "product_type",
                "purpose": null,
                .
                .
                .
            },
            ​​"loanType":1
        },
        {
            "status": 1,
            "debtorCompanyId": "debtor_company_id",
            "firstName": "first_name",
            "lastName": "last_name",
            "language": "en",
            "emiratesId": "emirates_id",
            "passportNumber": "passport_number",
            "birthDate": "birth_date",
            "gender": "male",
            "nationality": "",
            "phones": [
                {
                    "number": "*********",
                    "type": "work"
                }
            ],
            "emails": [
                {
                    "email": "[email protected]",
                    "type": null
                }
            ],
            "addresses": [
                {
                    "externalId": "external_uuid",
                    "street": null,
                    "city": null,
                    "area": null,
                    "zip": null,
                    "country": "three_characters_country", // eg UAE
                    "type": null
                }
            ],
            "accountId": "unique_account_id",
            "subAccountId": "unique_sub_account_id_2",
            "merchant": "merchant",
            "dateDue": "due_date",
            "principal": "principal_amount",
            "interest": "interest_amount",
            "fees": "fees",
            "paidAmount": "paid_amount",
            "paidDate": "paid_date",
            "additionalData": {
                "productType": "product_type",
                "purpose": null,
                .
                .
                .
            },
            ​​"loanType":1
        }
    ]
}

Details

Field	Descirption
accountId	Represents the main account or primary contract with the debtor. Example: A mobile phone purchase from an online store. All related financial obligations are grouped under this accountId.
subAccountId	Represents an individual obligation or installment under the main account. Each installment or fee is tracked as a unique subAccountId. Enables itemized tracking of payments and dues.
status	1 = create, 2 = update, 3 = withdraw
dates	All dates should be in dd/MM/yyyy format
additionalData	Any additional info regarding debt and borrower to be added in additionalData
country	Use alpha-3 code from this link
language	Pass en for english, ar for arabic
loanType	UAE 1 : CREDIT_CARD 2 : LEASE 3 : PERSONAL_LOAN 4 : BNPL 5 : CAR_RENTAL 6 : SUBSCRIPTION 7 :Charge Back 8 : SALARY_ADVANCE_LOAN

Dynamic Handling of Sub-Accounts

Because each sub-account is uniquely identified via subAccountId, the system supports flexible and real-time updates:

• Add anytime: New sub-accounts (e.g. new installment or charge) can be added independently at any time.

• Update anytime: Existing sub-accounts can be updated (fees change).

• Withdraw anytime: A sub-account can be withdrawn (e.g. removed or marked as cancelled).

• Any operation on a sub-account will automatically update the main accountId aggregate (e.g. outstanding balance, status, etc.).

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

Response

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

---

❌ Error Codes

Code	Message	Meaning
200	success	Request accepted
400	validation errors	Input error
401	unauthorized	Invalid/missing token
500	server error	Internal issue

---

🛠 Best Practices

• Always test first on dev environment before production.

• Use dd/MM/yyyy for dates.

• Pass en for English and ar for Arabic.

• Use subAccountId for installments or charges.

• Securely store your API credentials.