Search persons
curl --request POST \
--url https://partner-api.tryrima.com/v1/persons/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"limit": 50,
"offset": 0
}
'import requests
url = "https://partner-api.tryrima.com/v1/persons/search"
payload = {
"limit": 50,
"offset": 0
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({limit: 50, offset: 0})
};
fetch('https://partner-api.tryrima.com/v1/persons/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://partner-api.tryrima.com/v1/persons/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'limit' => 50,
'offset' => 0
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://partner-api.tryrima.com/v1/persons/search"
payload := strings.NewReader("{\n \"limit\": 50,\n \"offset\": 0\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://partner-api.tryrima.com/v1/persons/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"limit\": 50,\n \"offset\": 0\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://partner-api.tryrima.com/v1/persons/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"limit\": 50,\n \"offset\": 0\n}"
response = http.request(request)
puts response.read_body{
"asOf": "2026-10-13T15:00:00Z",
"persons": [
{
"id": "44444444-4444-4444-8444-444444444444",
"employments": [
{
"id": "11111111-1111-4111-8111-111111111111",
"companyId": "company_example",
"personId": "44444444-4444-4444-8444-444444444444",
"externalIds": [
{
"system": "payroll_system",
"system_id": "PAYROLL-001"
}
],
"demographics": {
"firstName": "Avery",
"lastName": "Morgan",
"dateOfBirth": "1990-04-12",
"gender": null
},
"contact": {
"email": "avery.morgan@example.com",
"phone": "+13125550100",
"address": {
"line1": "100 Example Street",
"line2": null,
"city": "Chicago",
"state": "IL",
"postalCode": "60601"
}
},
"membership": {
"status": "active",
"invitation": null
},
"participation": {
"decision": "opt_in",
"decidedAt": "2026-09-25T15:00:00Z"
},
"coverage": {
"status": "enrolled",
"startsAt": "2026-10-01",
"endsAt": "2026-12-31",
"planTier": "example_tier"
},
"createdAt": "2026-09-20T15:00:00Z",
"updatedAt": "2026-10-12T15:00:00Z"
}
],
"createdAt": "2026-09-20T15:00:00Z",
"updatedAt": "2026-10-12T15:00:00Z"
}
],
"pagination": {
"limit": 50,
"offset": 0,
"total": 1
}
}{
"error": "invalid_input"
}{
"error": "invalid_api_key"
}{
"error": "forbidden"
}{
"error": "rate_limited"
}{
"error": "internal_error"
}Search persons
For finding people across authorized employments.
POST
/
v1
/
persons
/
search
Search persons
curl --request POST \
--url https://partner-api.tryrima.com/v1/persons/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"limit": 50,
"offset": 0
}
'import requests
url = "https://partner-api.tryrima.com/v1/persons/search"
payload = {
"limit": 50,
"offset": 0
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({limit: 50, offset: 0})
};
fetch('https://partner-api.tryrima.com/v1/persons/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://partner-api.tryrima.com/v1/persons/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'limit' => 50,
'offset' => 0
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://partner-api.tryrima.com/v1/persons/search"
payload := strings.NewReader("{\n \"limit\": 50,\n \"offset\": 0\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://partner-api.tryrima.com/v1/persons/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"limit\": 50,\n \"offset\": 0\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://partner-api.tryrima.com/v1/persons/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"limit\": 50,\n \"offset\": 0\n}"
response = http.request(request)
puts response.read_body{
"asOf": "2026-10-13T15:00:00Z",
"persons": [
{
"id": "44444444-4444-4444-8444-444444444444",
"employments": [
{
"id": "11111111-1111-4111-8111-111111111111",
"companyId": "company_example",
"personId": "44444444-4444-4444-8444-444444444444",
"externalIds": [
{
"system": "payroll_system",
"system_id": "PAYROLL-001"
}
],
"demographics": {
"firstName": "Avery",
"lastName": "Morgan",
"dateOfBirth": "1990-04-12",
"gender": null
},
"contact": {
"email": "avery.morgan@example.com",
"phone": "+13125550100",
"address": {
"line1": "100 Example Street",
"line2": null,
"city": "Chicago",
"state": "IL",
"postalCode": "60601"
}
},
"membership": {
"status": "active",
"invitation": null
},
"participation": {
"decision": "opt_in",
"decidedAt": "2026-09-25T15:00:00Z"
},
"coverage": {
"status": "enrolled",
"startsAt": "2026-10-01",
"endsAt": "2026-12-31",
"planTier": "example_tier"
},
"createdAt": "2026-09-20T15:00:00Z",
"updatedAt": "2026-10-12T15:00:00Z"
}
],
"createdAt": "2026-09-20T15:00:00Z",
"updatedAt": "2026-10-12T15:00:00Z"
}
],
"pagination": {
"limit": 50,
"offset": 0,
"total": 1
}
}{
"error": "invalid_input"
}{
"error": "invalid_api_key"
}{
"error": "forbidden"
}{
"error": "rate_limited"
}{
"error": "internal_error"
}The JSON request body may be omitted. When supplied,
companyId and name filters must be nonempty. Phone input may include punctuation or an optional leading 1, but must normalize to exactly 10 digits. externalIdSystems accepts payroll_system and hhaexchange and selects returned IDs without filtering people.
Filters combine with AND. Company, name, and phone filters must match the same authorized employment. They select people without trimming a matching person’s returned employments array. An unsupported externalIdSystems value returns 400 invalid_input with a message naming the value. Other invalid filters and request bodies over 1 MiB also return 400 invalid_input; an unauthorized company filter returns 403 forbidden.
Results return each person once with all their employments in credential-authorized companies, including terminated records. Each employment is a complete Employee object with top-level participation and coverage. Pagination applies to people, not employments, and sorts by Person createdAt then id. Employee records without a Person link remain available through Search employees.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
JSON request body. Bodies over 1 MiB return 400 invalid_input.
Optional authorized company filter.
Minimum string length:
1Digits must normalize to exactly 10; an optional leading 1 is removed.
Case-insensitive partial match on an authorized employment.
Minimum string length:
1Case-insensitive partial match on an authorized employment.
Minimum string length:
1Exact Person UUID match.
Selects returned external IDs; does not filter records.
Available options:
payroll_system, hhaexchange Inclusive Person creation-time lower bound.
Exclusive Person creation-time upper bound.
Required range:
1 <= x <= 100Required range:
x >= 0