Skip to main content
GET
List persons in the caller's tenant with optional filtering and pagination.

Authorizations

x-api-key
string
header
required

Query Parameters

page
integer
default:1

Page number, 1-indexed. Clamped to >= 1.

per_page
integer
default:10

Results per page (default 10). Clamped to the range 1-50 (values outside are silently capped, not rejected).

after
string | null

Opaque cursor from a previous response's next_cursor. When supplied, the page starts immediately after the last record of that response and page is ignored — unlike page, this cannot skip or repeat records when the data changes mid-scan. Filters and sort must stay identical for the whole scan; changing one is a 400. Not supported by every list endpoint — those that support it return next_cursor.

name
string | null
email
string | null
linkedin_url
string | null
company_uuid
string | null

Filter to persons whose primary company affiliation is this company UUID. Matches the response's current_company.uuid.

job_title
string | null

Filter to persons whose current job title contains this text. Persons without a recorded job title are excluded.

city
string | null

Case-insensitive substring match on city.

state
string | null

State/region name; resolved via pycountry and matched case-insensitively against the stored canonical name (scoped to country when provided).

country
string | null

Country name or code; resolved via pycountry and matched case-insensitively against the stored canonical name.

modified_since
string | null

Return only persons modified at or after this ISO 8601 timestamp (e.g. '2025-01-01T00:00:00Z'). Tracks the last time Rings updated the record, from any source.

sort_by
enum<string> | null

Field to sort by. Valid values: 'name', 'last_activity_date'

Available options:
name,
last_activity_date
order
enum<string>
default:asc

Sort order. Valid values: 'asc' (ascending) or 'desc' (descending)

Available options:
asc,
desc
current_job_title
string | null

Case-insensitive substring match on the person's current job title (from the is_current=true employment row).

current_company_name
string | null

Case-insensitive substring match on the person's current company name.

current_company_domain
string | null

Exact match on the person's current company domain (e.g. 'acme.com').

job_changed_since
string | null

ISO 8601 timestamp — filter to persons whose current role started at or after this date (job_changed_at >= value).

job_changed_before
string | null

ISO 8601 timestamp — filter to persons whose current role started at or before this date (job_changed_at <= value).

previous_job_ended_since
string | null

ISO 8601 timestamp — filter to persons whose most-recent prior job ended at or after this date.

previous_job_ended_before
string | null

ISO 8601 timestamp — filter to persons whose most-recent prior job ended at or before this date.

uuids
string | null

Comma-separated list of person UUIDs to fetch. When set, only these persons are returned (subject to other filters).

Response

200 - application/json

Paginated list of persons.

items
PersonResponse · object[]
required
page
integer
required
per_page
integer
required
total
integer | null
required
has_more
boolean | null
next_cursor
string | null