LIlightsparkdev
Internal Accounts

List Customer internal accounts

Changed on

Retrieve a list of internal accounts with optional filtering parameters. Returns all internal accounts that match the specified filters. If no filters are provided, returns all internal accounts (paginated).

Internal accounts are created automatically when a customer is created based on the platform configuration.

get/customers/internal-accounts

Request

  • Base URL
    https://api.lightspark.com/grid/2025-10-13
  • URL
    https://api.lightspark.com/grid/2025-10-13/customers/internal-accounts
  • Auth
    HTTP basic

Query parameters

currencystring

Filter by currency code

customerIdstring

Filter by internal accounts associated with a specific customer

type'INTERNAL_FIAT' | 'INTERNAL_CRYPTO' | 'EMBEDDED_WALLET' | 'RULE_BASED' | 'BULK_SETTLEMENT'

Classification of an internal account.

  • INTERNAL_FIAT: A Grid-managed fiat holding account (for example, the USD holding account used as the source for Payouts flows).
  • INTERNAL_CRYPTO: A Grid-managed crypto holding account denominated in a stablecoin such as USDC.
  • EMBEDDED_WALLET: A self-custodial Embedded Wallet provisioned for the customer. Outbound transfers require a session signature produced by the customer's device — see the Embedded Wallets guide.
  • RULE_BASED: An additional account number for an existing account holder, with a routing rule attached, so incoming payments can be attributed to a specific payer and swept automatically. Created with POST /internal-accounts.
  • BULK_SETTLEMENT: An account for receiving bulk payments (for example, a single settlement from a payment processor) that the platform then pays out to its customers. Only a platform can hold one, and funds in it can move only to the platform's customers.

Filter by internal account type. Use EMBEDDED_WALLET to find the self-custodial wallet provisioned for a customer, INTERNAL_FIAT / INTERNAL_CRYPTO for the platform-managed holding accounts, or RULE_BASED for the additional account numbers issued for a customer.

limitinteger

Maximum number of results to return (default 20, max 100)

cursorstring

Cursor for pagination (returned from previous request)

Response

Successful operation

hasMoreboolean required

Indicates if more results are available beyond this page

nextCursorstring

Cursor to retrieve the next page of results (only present if hasMore is true)

totalCountinteger

Total number of customers matching the criteria (excluding pagination)

Example response

{
  "data": [
    {
      "id": "InternalAccount:12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "status": "ACTIVE",
      "balance": {
        "amount": 12550,
        "currency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "decimals": 2
        }
      },
      "totalBalance": {
        "amount": 12550,
        "currency": {
          "code": "USD",
          "name": "United States Dollar",
          "symbol": "$",
          "decimals": 2
        }
      },
      "fundingPaymentInstructions": [
        {
          "instructionsNotes": "Please ensure the reference code is included in the payment memo/description field",
          "isPlatformAccount": true,
          "accountOrWalletInfo": {
            "accountType": "USD_ACCOUNT",
            "accountNumber": "1234567890",
            "routingNumber": "021000021",
            "bankName": "Chase Bank",
            "intermediaryBankName": "JPMorgan Chase Bank",
            "intermediaryRoutingNumber": "021000021",
            "fiToFiInformation": "/BNF/Invoice 4471",
            "bankAccountType": "CHECKING"
          }
        }
      ],
      "onBehalfOfCustomerId": "Customer:019542f5-b3e7-1d02-0000-000000000002",
      "label": "invoice-4417",
      "sweepRule": {
        "destination": {
          "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
          "paymentRail": "ACH"
        },
        "minimumAmount": {
          "amount": 12550,
          "currency": {
            "code": "USD",
            "name": "United States Dollar",
            "symbol": "$",
            "decimals": 2
          }
        },
        "maximumAmount": {
          "amount": 12550,
          "currency": {
            "code": "USD",
            "name": "United States Dollar",
            "symbol": "$",
            "decimals": 2
          }
        },
        "description": "Rent sweep",
        "remittanceInformation": "Unit 4B March",
        "platformFeeOverride": {
          "platformFixedFee": {
            "amount": 50,
            "currency": "USD"
          },
          "platformVariableFeeBps": 30
        }
      },
      "privateEnabled": true,
      "cardCapabilities": {
        "supportsVelocityLimits": true,
        "supportsPanReveal": true,
        "supportsDigitalWalletTokenization": true
      },
      "createdAt": "2025-10-03T12:30:00Z",
      "updatedAt": "2025-10-03T12:30:00Z"
    }
  ]
}

Changes

  • d996ddfb9d2bRevision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • 5fbda612feb8Revision changes
    • breaking

      removed the required property /// from the response with the status

    • breaking

      removed the required property /// from the response with the status

    • breaking

      removed the required property /// from the response with the status

    • info

      added the required property /// to the response with the status