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 on the person's city (e.g. 'Los Angeles'). Pass the full city name, not an abbreviation — 'LA' is matched as a substring and hits Dallas and Cleveland, not Los Angeles.

state
string | null

Person's state/region. A full name ('Florida') works on its own; a two-letter code ('FL', 'NY') is ISO 3166-2 and requires country, since unscoped 'CA' means Alberta and 'FL' means Flintshire, GB. Returns 400 if it does not resolve, rather than an empty page that reads as 'nobody there'.

country
string | null

Person's country, name or ISO code ('US', 'United States'). Required next to a two-letter state. Returns 400 if unrecognized.

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.

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