Records

Search records

List and filter records of a single record type. Despite the POST verb this is a read - the criteria travel in the body. Supports filtering, sorting, sparse fieldsets, relationship includes, time-range narrowing, and keyset pagination.

post/api/v2/records/search

Request

  • Base URL: https://your-tenant.tines.com
  • URL: https://your-tenant.tines.com/api/v2/records/search
  • Auth: one of:
    • API key in header X-User-Token
    • HTTP bearer

Request body

record_type_idinteger

Numeric record type id. Takes precedence when record_type_name is also provided.

record_type_namestring

Record type name or slug. Used when record_type_id is omitted.

filterobject

Filter tree: a single condition { field_id | field_name, operator, value }, or an AND group { "op": "AND", "nodes": [...] } (max depth 4, 50 nodes). Only AND is supported. field_name matches a field name or slug; matching is insensitive to case and separators. Available operators depend on the field type (e.g. TEXT: EQUAL, CONTAINS, IS_ANY_OF; NUMBER: GREATER_THAN, LESS_THAN; TIMESTAMP: GREATER_THAN, LESS_THAN).

sortobject[]

Ordered sort keys, each { field_id | field_name, direction } where direction is ASC or DESC. field_name matches a field name or slug; matching is insensitive to case and separators. created_at is accepted as a field name.

fieldsobject

Sparse fieldset, e.g. { "record": "status,severity" }. Matching is insensitive to case and separators. Omit for all fields.

includestring[]

To-one relationships to embed. record_type is embedded under included; parent_record rides in each record's relationships.

idsinteger[]

Hydrate specific record ids (max 500). Cannot be combined with after.

timezonestring

IANA timezone applied to time-range presets and timestamp output. Defaults to UTC.

limitinteger

Page size, 1-500. Defaults to 20.

afterstring

Opaque forward pagination cursor from page.next_page_token.

include_totalboolean

When true, include page.total. Defaults to false.

test_modeboolean

When true, search test records instead of live records. Requires change control. Defaults to false.

Response

Successful response

field_idsobject

Map of each returned field's slug key to its immutable field id.

includedobject

Present only when include is used. record_type is a one-element array of { id, name, slug }.

Changes

No recorded changes to this operation across all 1 revision of this API.