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:50

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

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. Same source as the response's current_company.uuid (highest-priority PrimaryAffiliation).

job_title
string | null

Filter to persons whose current job title contains this text. Backed by a recently-added column still being backfilled for existing records, so coverage may be incomplete for a while.

modified_since
string | null

Return only persons modified at or after this ISO 8601 timestamp (e.g. '2025-01-01T00:00:00Z'). Filtered on the rings_updated_at field which tracks the last time Rings updated the record.

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
required