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

# Load your first book

> Send your existing Customers and Receivables to PayPathIQ in batches, then check the result.

A book is all the open Receivables in your source system. This guide loads a small book with one batch. It uses the sandbox and synthetic data. Finish the [quickstart](/quickstart) first so you have a key and a `clientCode`. Terms are in the [glossary](/glossary).

## Before you load

* Choose a stable, opaque [external ID](/glossary) for every Customer and Receivable. Do not use member numbers or loan numbers.
* Plan the order. A Receivable can reference only Customers that already exist, so list Customers first.
* Decide your retry rule. A batch is safe to resend with the same ID and body. See [Safe retries](/idempotency).

## Step 1: Queue a batch

A batch holds up to 100 records. Each record is `{ recordId, kind, externalId, body }`. The `body` is exactly the body of the matching single-record `PUT`. Use `dependsOn` so a Receivable runs only if its Customer succeeded.

<CodeGroup>
  ```bash curl theme={null}
  curl --include \
    --request PUT \
    --url "$PAYPATHIQ_BASE_URL/v1/clients/$PAYPATHIQ_CLIENT_CODE/batches/BAT_FIRST_LOAD" \
    --header "Authorization: Bearer $PAYPATHIQ_SANDBOX_API_KEY" \
    --header 'Content-Type: application/json' \
    --data '{
      "records": [
        {
          "recordId": "r1",
          "kind": "customer",
          "externalId": "CUS_B001",
          "body": {
            "type": "person",
            "name": { "firstName": "Avery", "lastName": "Example" }
          }
        },
        {
          "recordId": "r2",
          "kind": "receivable",
          "externalId": "REC_B001",
          "dependsOn": ["r1"],
          "body": {
            "financialType": "loan_balance",
            "sourceRevision": 1,
            "sourceReference": "receivable-ref-b001",
            "responsibleCustomers": [{ "externalCustomerId": "CUS_B001", "role": "primary" }],
            "recoverableAmount": { "amount": "1250.00", "currency": "EUR" },
            "dueDate": "2026-08-01",
            "creditUnion": {
              "loanAccountReference": "loan-ref-b001",
              "loanType": "personal_loan",
              "arrearsAmount": { "amount": "1250.00", "currency": "EUR" }
            }
          }
        }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const base = "https://api.sandbox.paypathiq.com";
  const clientCode = process.env.PAYPATHIQ_CLIENT_CODE;
  const headers = {
    Authorization: `Bearer ${process.env.PAYPATHIQ_SANDBOX_API_KEY}`,
    "Content-Type": "application/json",
  };

  const response = await fetch(`${base}/v1/clients/${clientCode}/batches/BAT_FIRST_LOAD`, {
    method: "PUT",
    headers,
    body: JSON.stringify({
      records: [
        {
          recordId: "r1",
          kind: "customer",
          externalId: "CUS_B001",
          body: { type: "person", name: { firstName: "Avery", lastName: "Example" } },
        },
        {
          recordId: "r2",
          kind: "receivable",
          externalId: "REC_B001",
          dependsOn: ["r1"],
          body: {
            financialType: "loan_balance",
            sourceRevision: 1,
            sourceReference: "receivable-ref-b001",
            responsibleCustomers: [{ externalCustomerId: "CUS_B001", role: "primary" }],
            recoverableAmount: { amount: "1250.00", currency: "EUR" },
            dueDate: "2026-08-01",
            creditUnion: {
              loanAccountReference: "loan-ref-b001",
              loanType: "personal_loan",
              arrearsAmount: { amount: "1250.00", currency: "EUR" },
            },
          },
        },
      ],
    }),
  });
  console.log(response.status, await response.json());
  ```

  ```python Python theme={null}
  import os
  import requests

  base = "https://api.sandbox.paypathiq.com"
  client_code = os.environ["PAYPATHIQ_CLIENT_CODE"]
  headers = {"Authorization": f"Bearer {os.environ['PAYPATHIQ_SANDBOX_API_KEY']}"}

  response = requests.put(
      f"{base}/v1/clients/{client_code}/batches/BAT_FIRST_LOAD",
      headers=headers,
      json={
          "records": [
              {
                  "recordId": "r1",
                  "kind": "customer",
                  "externalId": "CUS_B001",
                  "body": {"type": "person", "name": {"firstName": "Avery", "lastName": "Example"}},
              },
              {
                  "recordId": "r2",
                  "kind": "receivable",
                  "externalId": "REC_B001",
                  "dependsOn": ["r1"],
                  "body": {
                      "financialType": "loan_balance",
                      "sourceRevision": 1,
                      "sourceReference": "receivable-ref-b001",
                      "responsibleCustomers": [{"externalCustomerId": "CUS_B001", "role": "primary"}],
                      "recoverableAmount": {"amount": "1250.00", "currency": "EUR"},
                      "dueDate": "2026-08-01",
                      "creditUnion": {
                          "loanAccountReference": "loan-ref-b001",
                          "loanType": "personal_loan",
                          "arrearsAmount": {"amount": "1250.00", "currency": "EUR"},
                      },
                  },
              },
          ]
      },
      timeout=30,
  )
  print(response.status_code, response.json())
  ```
</CodeGroup>

**Expect `202 Accepted`.** That means the batch is durably queued. It does not mean any record was accepted. The batch needs the write scope for every kind of record in it, here `customers:write` and `receivables:write`. A connection can have at most 2 queued or running batches at once.

## Step 2: Check progress

Send a `GET` to the same URL until the batch `status` is no longer `queued` or `running`.

```bash theme={null}
curl --url "$PAYPATHIQ_BASE_URL/v1/clients/$PAYPATHIQ_CLIENT_CODE/batches/BAT_FIRST_LOAD" \
  --header "Authorization: Bearer $PAYPATHIQ_SANDBOX_API_KEY"
```

The final `status` is `succeeded`, `partially_succeeded` or `failed`. Each record reports `succeeded`, `failed` (with the `httpStatus` and `problem.type` a single request would return), `dependency_failed` or `pending`.

## Step 3: Fix failures

Fix the data for any failed record. Send it again in a new batch, or through its single-record `PUT`. A record marked `dependency_failed` was not attempted, because the record it depends on did not succeed.

## Step 4: Declare the book complete (optional)

Leaving a Receivable out of a batch changes nothing. If you want PayPathIQ to flag open Receivables that are missing from your book, declare it complete after every batch has succeeded. See [Complete books and missing records](/concepts#complete-books-and-missing-records). A declaration needs the batch IDs and the exact Receivable count, and a failed or partial load is refused with `409 book_completion_unverified`.

## Next steps

* [Report a payment](/report-a-payment)
* [Stay in sync with the change feed](/stay-in-sync)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.