Sync Patterns

Webhooks

Webhooks are in development and will provide real-time notifications when receivables change, eliminating the need for polling. Webhooks →

Recommended Approach

Loading diagram...

Local Storage Schema

CREATE TABLE receivables (
  id SERIAL PRIMARY KEY,
  kapwork_id VARCHAR(40) UNIQUE NOT NULL,  -- rcv_ + 32 hex chars
  vendor_name VARCHAR(255),
  debtor_name VARCHAR(255),
  amount_cents BIGINT,
  status VARCHAR(50),
  portal_status VARCHAR(255),
  detected_at TIMESTAMP,
  updated_at TIMESTAMP,
  synced_at TIMESTAMP DEFAULT NOW()
);

The kapwork_id column stores our identifier (e.g., rcv_550e8400e29b41d4a716446655440000). You cannot create receivables via the API; this ID is how you track updates over time.

Initial Load

Fetch all historical receivables:

GET /v1/receivables?verified_since=all

Paginate through results using page and limit parameters.

Daily Sync

Run a scheduled job daily:

GET /v1/receivables

By default, this returns receivables updated in the last 24 hours.

Upsert Logic

for receivable in response['data']:
    if exists_in_db(receivable['id']):
        update_receivable(receivable)
    else:
        insert_receivable(receivable)

Time Range Parameters

Query	Returns
`GET /v1/receivables`	Last 24 hours (default)
`GET /v1/receivables?verified_since=all`	All receivables
`GET /v1/receivables?verified_since=2026-01-01T00:00:00Z`	Since specified date

The `expand[]` Parameter

Include additional data in list responses:

# Include change history
GET /v1/receivables?expand[]=history

# Include portal metadata
GET /v1/receivables?expand[]=metadata

# Include both
GET /v1/receivables?expand[]=history&expand[]=metadata

Single receivable requests (GET /v1/receivables/:id) include history and metadata by default.

History Limit

# Last 50 changes (default is 10)
GET /v1/receivables/:id?history_limit=50

Pagination

Parameter	Default	Maximum
`page`	1	—
`limit`	100	500

The response includes has_more: true when additional pages exist.

GET /v1/receivables?page=1&limit=100
GET /v1/receivables?page=2&limit=100

Recommendations

Store kapwork_id — Track updates over time
Use pagination — Handle large datasets
Check estimated_next_update_at — Determine when to re-sync
Use history — See changes without additional requests
Use portal_status — For display and audit purposes