Find records, choose fields, and paginate

Fetch a page of candidates and select the fields an integration needs. Start with a small query, verify its results, and add filters afterward.

Before you begin

Read API authentication, identify the object’s internal name, and confirm record/property read permissions. mainObject chooses the object context, such as candidate; it is not a record UUID.

Fetch the first page

curl -X POST 'https://v2.api.caraer.com/api/v2/records/index?parse=true' \
  -H "Authorization: Bearer $CARAER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"mainObject":"candidate","page":1,"limit":25}'

Inspect the returned page before increasing its size. Request following pages with the same query and an increasing page. Use the response’s pagination information to decide when the result is complete.

Choose fields and sorting

Show items (show) and how * works

show controls which fields are returned for each record.

Basic shape:

{
  "show": [
    { "object": "candidate", "relation": null, "property": "firstname" },
    { "object": "candidate", "relation": null, "property": "email" }
  ]
}

Using * in show

You can request all readable properties of the main object with:

{
  "show": [{ "object": "candidate", "relation": null, "property": "*" }]
}

Important behavior:

• * expansion is applied for the main object wildcard pattern.
• Backend resolves it to all readable properties for that main object.
• Access rules still apply: only properties the caller can read are returned.

If you need a stable API response contract, explicitly list the properties instead of relying on *.

Sort items (sort)

sort controls ordering of result rows.

Basic shape:

{
  "sort": [
    {
      "object": "candidate",
      "relation": null,
      "property": "updatedAt",
      "direction": "DESC"
    }
  ]
}

Rules:

• direction supports ASC and DESC.
• You can provide multiple sort items to create secondary/tertiary ordering.
• Use properties that exist and are readable in the requested context.

Example with fallback ordering:

{
  "sort": [
    {
      "object": "candidate",
      "relation": null,
      "property": "status_candidate",
      "direction": "ASC"
    },
    {
      "object": "candidate",
      "relation": null,
      "property": "updatedAt",
      "direction": "DESC"
    }
  ]
}

Add filters when the basic query works

The filter guide explains groups, operators, related records, and combining search with sorting. Always include the intended object on sort items; filter object/relation fields have their own rules.

Include archived records deliberately

archived=true selects archived records. The default list selects active records. Use the same POST /api/v2/records/index endpoint and query body; do not construct an object-specific GET index URL.

Common mistakes

Confusing object names and UUIDs, relying on * for a stable integration, and changing a query while paging can give unexpected results. Validate the first page and use explicit fields for long-lived integrations.

See the Records API reference for current pagination and query fields.