Working with records

Create, read, update, delete and bulk-load records, and move them through flows, with the API.

Records are the core of the klerc API. This page walks through the common operations with a Motor Policy object as the example. Every endpoint is in the objects reference.

Find the object#

Record endpoints take an objectId. List your objects to find it:

bash

curl "https://api.klerc.co/api/v1/objects" \  -H "Authorization: Bearer $KLERC_TOKEN"

GET /objects accepts a q parameter to filter by name, and GET /objects/{id} returns one object's schema — its fields and their keys. Field keys, such as policy_number, are what you send in data.

Create a record#

http

POST /api/v1/objects/{objectId}/records

json

{  "data": {    "policy_number": "MAXLIFE/2024/101608",    "premium": 18400,    "expiry_date": "2026-09-18"  },  "owner": "USER_ID"}

data is required; owner is optional. Required-field and uniqueness rules apply exactly as in the console. Creating records needs objects:use.

Read and list#

GET /objects/records/{id} returns one record.
GET /objects/{objectId}/records lists records, with limit and cursor for paging, sort and dir for ordering, and filter to narrow the list.

For anything beyond simple listing — joins, aggregates, complex conditions — use POST /query. Reading needs objects:view.

Update#

Send only the fields you're changing:

http

PATCH /api/v1/objects/records/{id}

json

{ "data": { "premium": 19200 } }

The change is written to the record's history and the audit log, and it can trigger workflows just like an edit in the console.

Delete#

DELETE /objects/records/{id} deletes a record. Deleting needs objects:use.

Bulk-create#

Load many records in one call:

http

POST /api/v1/objects/{objectId}/records/bulk

json

{  "records": [    { "policy_number": "STAR/2025/102309", "premium": 12600 },    { "policy_number": "CHOLA/2025/101116", "premium": 9800 }  ]}

Each item is a record's fields, keyed the same way as data. The reference doesn't document a maximum batch size; keep batches to a few hundred and check each response before sending the next.

Put a record on a flow#

Add the record to a pipeline, then move it on:

json

{ "record": "RECORD_ID", "stage": "STAGE" }

That goes to POST /flows/{flowId}/states. Then POST /flows/states/{id}/transition with { "toStage": "STAGE" } moves it. See Pipelines for how stage rules apply.