> ## Documentation Index
> Fetch the complete documentation index at: https://docs.command.cleargrid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create & Update Account

> Create new accounts, update existing ones, or withdraw accounts from the collection portfolio

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

<ParamField header="Authorization" type="string" required>
  Bearer token obtained from the [Lender Login](/api-reference/authentication/lender-login) endpoint. Format: `Bearer <access_token>`
</ParamField>

### Body Parameters

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

<ParamField body="accounts" type="array" required>
  An array of account objects. You can include multiple accounts and sub-accounts in a single request.

  <Expandable title="Account object fields">
    <ParamField body="status" type="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 |
    </ParamField>

    <ParamField body="debtorCompanyId" type="string" required>
      Unique identifier for the debtor/customer in your system.
    </ParamField>

    <ParamField body="firstName" type="string" required>
      The borrower's first name.
    </ParamField>

    <ParamField body="lastName" type="string" required>
      The borrower's last name.
    </ParamField>

    <ParamField body="language" type="string" required>
      Preferred language for communication. Use `en` for English, `ar` for Arabic.
    </ParamField>

    <ParamField body="idNumber" type="string">
      National identification number. For UAE, use the Emirates ID. For Saudi Arabia, use the National ID.
    </ParamField>

    <ParamField body="passportNumber" type="string">
      Borrower's passport number.
    </ParamField>

    <ParamField body="birthDate" type="string">
      Date of birth in `dd/MM/yyyy` format.
    </ParamField>

    <ParamField body="gender" type="string">
      Borrower's gender. Accepted values: `male`, `female`.
    </ParamField>

    <ParamField body="nationality" type="string">
      Borrower's nationality.
    </ParamField>

    <ParamField body="phones" type="array">
      Array of phone number objects.

      <Expandable title="Phone object fields">
        <ParamField body="number" type="string" required>
          The phone number.
        </ParamField>

        <ParamField body="type" type="string">
          The phone type. Examples: `work`, `home`, `mobile`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="emails" type="array">
      Array of email address objects.

      <Expandable title="Email object fields">
        <ParamField body="email" type="string" required>
          The email address.
        </ParamField>

        <ParamField body="type" type="string">
          The email type. Examples: `work`, `personal`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="addresses" type="array">
      Array of address objects.

      <Expandable title="Address object fields">
        <ParamField body="externalId" type="string">
          External UUID for the address in your system.
        </ParamField>

        <ParamField body="street" type="string">
          Street address.
        </ParamField>

        <ParamField body="city" type="string">
          City name.
        </ParamField>

        <ParamField body="area" type="string">
          Area or district.
        </ParamField>

        <ParamField body="zip" type="string">
          Postal / ZIP code.
        </ParamField>

        <ParamField body="country" type="string">
          Three-character country code ([ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)). Example: `ARE` for UAE, `SAU` for Saudi Arabia.
        </ParamField>

        <ParamField body="type" type="string">
          Address type. Examples: `home`, `work`, `billing`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="accountId" type="string" required>
      The main account identifier representing the primary contract with the debtor. All related sub-accounts are grouped under this ID.
    </ParamField>

    <ParamField body="subAccountId" type="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.
    </ParamField>

    <ParamField body="merchant" type="string">
      The merchant or business associated with the debt.
    </ParamField>

    <ParamField body="dateDue" type="string">
      The due date for this account/installment in `dd/MM/yyyy` format.
    </ParamField>

    <ParamField body="principal" type="string" required>
      The principal amount owed.
    </ParamField>

    <ParamField body="interest" type="string">
      The interest amount.
    </ParamField>

    <ParamField body="fees" type="string">
      Any additional fees.
    </ParamField>

    <ParamField body="paidAmount" type="string">
      The amount already paid by the borrower.
    </ParamField>

    <ParamField body="paidDate" type="string">
      The date of the last payment in `dd/MM/yyyy` format.
    </ParamField>

    <ParamField body="additionalData" type="object">
      A flexible key-value object for storing any additional metadata about the account. Common fields include `productType`, `purpose`, and other business-specific attributes.
    </ParamField>

    <ParamField body="loanType" type="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      |
    </ParamField>
  </Expandable>
</ParamField>

## Example Request

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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:**

    1. Status `1`: Create account with principal of 100, paidAmount of 0
    2. Status `2`: Update with paidAmount of 30 (balance becomes 70)
    3. Status `2`: Update with paidAmount of 50 (balance becomes 50)
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Important Notes

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

<Info>
  **Country codes:** Use [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) three-character codes (e.g., `ARE` for UAE, `SAU` for Saudi Arabia, `BHR` for Bahrain).
</Info>

<Info>
  **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.
</Info>

## Response

<Tabs>
  <Tab title="200 — Success">
    Data has been accepted and processing has started in the background.

    ```json theme={null}
    {
      "code": 200,
      "message": "success",
      "body": "Processing started successfully",
      "errors": []
    }
    ```
  </Tab>

  <Tab title="400 — Validation Error">
    One or more accounts in the request failed validation. The `errors` array contains details for each failed account.

    ```json theme={null}
    {
      "code": 400,
      "message": null,
      "body": "",
      "errors": [
        {
          "accountId": "ORD-2025-001",
          "errors": [
            "firstName is required",
            "principal must be a valid number"
          ]
        }
      ]
    }
    ```
  </Tab>

  <Tab title="401 — Unauthorized">
    ```json theme={null}
    {
      "error": "Unauthorized"
    }
    ```

    The access token is missing, invalid, or expired. Re-authenticate using the [Lender Login](/api-reference/authentication/lender-login) or [Refresh Token](/api-reference/authentication/refresh-token) endpoint.
  </Tab>

  <Tab title="500 — Server Error">
    ```json theme={null}
    {
      "error": "Something went wrong. Please try again later."
    }
    ```

    An unexpected server error occurred. If this persists, contact ClearGrid support.
  </Tab>
</Tabs>


## OpenAPI

````yaml /api-reference/openapi.json POST /admin/v3/lenders/{lenderPublicId}/accounts
openapi: 3.1.0
info:
  title: Command API
  description: >-
    RESTful API for lenders to manage accounts and borrower data in the Command
    platform.
  version: 3.0.0
servers:
  - url: https://v3-api.cleargrid.ai
    description: Production
  - url: https://stage-v3-api.cleargrid.ai
    description: Staging
security: []
paths:
  /admin/v3/lenders/{lenderPublicId}/accounts:
    post:
      tags:
        - Lender Accounts
      summary: Create or update accounts
      description: >-
        Create new accounts, update existing ones, or withdraw accounts from the
        collection portfolio. Supports multiple accounts and sub-accounts in a
        single request. Processed asynchronously in the background.
      operationId: upsertAccounts
      parameters:
        - in: path
          name: lenderPublicId
          required: true
          schema:
            type: string
          description: Lender public ID (UUID) returned by the Lender Login endpoint.
          example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accounts
              properties:
                accounts:
                  type: array
                  description: Array of account objects to create, update, or withdraw.
                  items:
                    type: object
                    required:
                      - accountId
                      - status
                      - debtorCompanyId
                      - firstName
                      - birthDate
                      - dateDue
                      - principal
                      - phones
                      - loanType
                    properties:
                      accountId:
                        type: string
                        example: ORD-2025-001
                        description: >-
                          The main account identifier representing the primary
                          contract with the debtor.
                      subAccountId:
                        type: string
                        example: PMT-2025-001-01
                        description: >-
                          A unique identifier for an individual obligation or
                          installment under the main account.
                      status:
                        type: integer
                        enum:
                          - 1
                          - 2
                          - 3
                        example: 1
                        description: 'Operation: 1 = Create, 2 = Update, 3 = Withdraw'
                      debtorCompanyId:
                        type: string
                        example: customer_001
                        description: >-
                          Unique identifier for the debtor/customer in your
                          system.
                      firstName:
                        type: string
                        example: Ahmed
                        description: The borrower's first name.
                      lastName:
                        type: string
                        example: Al Maktoum
                        description: The borrower's last name.
                      language:
                        type: string
                        enum:
                          - en
                          - ar
                        example: en
                        description: Preferred language for communication.
                      emiratesId:
                        type: string
                        example: 784-1990-1234567-1
                        description: Emirates ID number (UAE).
                      idNumber:
                        type: string
                        example: 784-1990-1234567-1
                        description: >-
                          National identification number. For UAE use Emirates
                          ID; for Saudi Arabia use National ID.
                      passportNumber:
                        type: string
                        example: P1234567
                        description: Borrower's passport number.
                      birthDate:
                        type: string
                        example: 15/06/1990
                        description: Date of birth in dd/MM/yyyy format.
                      gender:
                        type: string
                        example: male
                        description: 'Borrower''s gender. Accepted: male, female.'
                      nationality:
                        type: string
                        example: Emirati
                        description: Borrower's nationality.
                      merchant:
                        type: string
                        example: TechStore UAE
                        description: The merchant or business associated with the debt.
                      dateDue:
                        type: string
                        example: 01/03/2026
                        description: >-
                          The due date for this account/installment in
                          dd/MM/yyyy format.
                      principal:
                        type: string
                        example: '5000'
                        description: The principal amount owed.
                      interest:
                        type: string
                        example: '250'
                        description: The interest amount.
                      fees:
                        type: string
                        example: '50'
                        description: Any additional fees.
                      paidAmount:
                        type: string
                        example: '0'
                        description: The amount already paid by the borrower.
                      paidDate:
                        type: string
                        example: 01/02/2026
                        description: The date of the last payment in dd/MM/yyyy format.
                      phones:
                        type: array
                        description: Array of phone number objects.
                        items:
                          $ref: '#/components/schemas/Phone'
                      emails:
                        type: array
                        description: Array of email address objects.
                        items:
                          $ref: '#/components/schemas/Email'
                      addresses:
                        type: array
                        description: Array of address objects.
                        items:
                          $ref: '#/components/schemas/Address'
                      loanType:
                        type: integer
                        enum:
                          - 1
                          - 2
                          - 3
                          - 4
                          - 5
                          - 6
                          - 7
                          - 8
                        example: 4
                        description: >-
                          Type of loan: 1=Credit Card, 2=Lease, 3=Personal Loan,
                          4=BNPL, 5=Car Rental, 6=Subscription, 7=Charge Back,
                          8=Salary Advance Loan
                      additionalData:
                        type: object
                        example:
                          productType: Electronics
                          purpose: Mobile phone purchase
                        description: >-
                          Flexible key-value object for any additional metadata
                          about the account.
            example:
              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
      responses:
        '200':
          description: Processing started successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardError'
              example:
                code: 200
                message: success
                body: Processing started successfully
                errors: []
        '400':
          description: Bad request — one or more accounts failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardError'
              example:
                code: 400
                message: null
                body: ''
                errors:
                  - accountId: ORD-2025-001
                    errors:
                      - firstName is required
                      - principal must be a valid number
        '401':
          description: Unauthorized — missing, invalid, or expired token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: Unauthorized
      security:
        - bearerAuth: []
components:
  schemas:
    Phone:
      type: object
      properties:
        number:
          type: string
          example: '+971501234567'
        type:
          type: string
          example: mobile
    Email:
      type: object
      properties:
        email:
          type: string
          example: ahmed@example.com
        type:
          type: string
          example: personal
    Address:
      type: object
      properties:
        externalId:
          type: string
          example: addr-uuid-001
        street:
          type: string
          example: Sheikh Zayed Road
        city:
          type: string
          example: Dubai
        area:
          type: string
          example: Downtown
        zip:
          type: string
          example: '00000'
        country:
          type: string
          example: ARE
          description: ISO 3166-1 alpha-3 country code (e.g. ARE, SAU, BHR)
        type:
          type: string
          example: home
    StandardError:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
          nullable: true
        body:
          type: string
        errors:
          type: array
          items:
            type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````