> ## Documentation Index > Fetch the complete documentation index at: https://docs.api.ignitehealth.com/llms.txt > Use this file to discover all available pages before exploring further. # Search persons > For finding people across authorized employments. The JSON request body may be omitted. Without a `companyId` filter, the search covers every company allowed by the key. `firstName`, `lastName`, `fullName`, and `email` use case-insensitive partial matching on an employment. `employeeId` selects a matching employment by UUID. `personId` selects a Person by UUID. `dateOfBirth` is a calendar date in `YYYY-MM-DD` format, and `createdFrom` is an inclusive lower bound on Person creation time. Phone matching strips nondigits and uses the last 10 digits of the input. Shorter partial numbers also match. A nonempty phone value with no digits is invalid. Empty-string fields are ignored, and text filters are limited to 100 characters. `externalIdSystems` accepts `payroll_system` and `hhaexchange` and selects returned IDs without filtering people. Filters combine with AND. Company, name, email, phone, date-of-birth, and employee-ID filters must match the same authorized employment. They select people without trimming a matching person's returned `employments` array. An unsupported `externalIdSystems` value, an unknown field whose value is not an empty string, or an overlong text filter returns `400 invalid_input` with a message naming the value or field. Other invalid filters and request bodies over 1 MiB also return `400 invalid_input`. A company ID not accessible to the key returns `403 forbidden`. Results return each person once with all their non-archived 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](https://docs.api.ignitehealth.com/search-employees.md). ## OpenAPI ````yaml openapi.json POST /v1/persons/search openapi: 3.1.0 info: title: Ignite Partner API version: 0.0.1 description: >- Request access from Ignite at [dev@ignitehealth.com](mailto:dev@ignitehealth.com). Provide your organization name, technical contact, intended use, companies you need to access, and requested environments. Use `https://sandbox-api.ignitehealth.com` for sandbox and `https://api.ignitehealth.com` for production. Send requests from your backend with `Authorization: Bearer `. Keep the key in a secrets manager and out of email, support requests, and shared documents. Keys are scoped to approved operations and companies. Responses include `x-request-id`. Include that ID and the request timestamp when reporting a failed request. Never include the key. servers: - url: https://api.ignitehealth.com description: Ignite production - url: https://sandbox-api.ignitehealth.com description: Ignite sandbox security: [] paths: /v1/persons/search: post: summary: Search persons requestBody: required: false content: application/json: schema: type: object properties: companyId: type: string description: Optional authorized company filter. maxLength: 100 phone: type: string description: >- Nondigits are removed. The last 10 digits are used for matching. Partial numbers are accepted, but a nonempty value with no digits is invalid. maxLength: 100 firstName: type: string description: Case-insensitive partial match on an authorized employment. maxLength: 100 lastName: type: string description: Case-insensitive partial match on an authorized employment. maxLength: 100 fullName: type: string description: >- Case-insensitive partial match on an authorized employment's full name. maxLength: 100 email: type: string description: Case-insensitive partial match on an authorized employment. maxLength: 100 employeeId: type: string description: >- Exact Employee-record UUID match on an authorized employment. format: uuid dateOfBirth: type: string description: Exact calendar date match on an authorized employment. format: date personId: type: string description: Exact Person UUID match. format: uuid externalIdSystems: type: array description: >- Specifies which external IDs to return. It does not filter records. items: type: string createdFrom: type: string description: >- Set an inclusive lower bound on Person creation time. Include seconds and a timezone. format: date-time limit: type: integer minimum: 1 maximum: 100 default: 50 offset: type: integer minimum: 0 maximum: 9007199254740991 default: 0 additionalProperties: const: '' example: limit: 50 offset: 0 description: >- Optional JSON object. Empty-string fields are ignored. Other unsupported fields return 400 invalid_input. Bodies over 1 MiB return 400 invalid_input. responses: '200': description: Person search results. content: application/json: schema: type: object properties: asOf: type: string format: date-time persons: type: array items: $ref: '#/components/schemas/Person' pagination: $ref: '#/components/schemas/Pagination' required: - asOf - persons - pagination examples: example: value: 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 '400': $ref: '#/components/responses/InvalidInput' '401': $ref: '#/components/responses/InvalidApiKey' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - bearerAuth: [] components: schemas: Person: type: object properties: id: type: string description: Person UUID. format: uuid employments: type: array description: Complete non-archived Employee objects in authorized companies. items: $ref: '#/components/schemas/Employee' createdAt: type: string format: date-time updatedAt: type: string description: >- This is the Person-row timestamp. It is not a watermark for nested employment data. format: date-time required: - id - employments - createdAt - updatedAt Pagination: type: object properties: limit: type: integer offset: type: integer total: type: integer required: - limit - offset - total Employee: type: object properties: id: type: string description: Employee-record UUID. format: uuid companyId: type: string description: Company ID. personId: type: - string - 'null' description: >- This is the linked Person UUID. It is null when identity is unresolved. format: uuid externalIds: type: array description: Identifiers in external systems. items: type: object properties: system: type: string description: External system name. system_id: type: string required: - system - system_id demographics: type: object properties: firstName: type: - string - 'null' lastName: type: - string - 'null' dateOfBirth: type: - string - 'null' format: date gender: type: - string - 'null' required: - firstName - lastName - dateOfBirth - gender contact: type: object properties: email: type: - string - 'null' phone: type: - string - 'null' address: type: object properties: line1: type: - string - 'null' line2: type: - string - 'null' city: type: - string - 'null' state: type: - string - 'null' postalCode: type: - string - 'null' required: - line1 - line2 - city - state - postalCode required: - email - phone - address membership: type: object properties: status: type: string description: >- This is derived from membership, invitation, and linked user state. Membership takes precedence. enum: - not_invited - invited_pending - invited_expired - active - revoked_access invitation: type: - object - 'null' properties: status: type: string invitedAt: type: string format: date-time expiresAt: type: string format: date-time required: - status - invitedAt - expiresAt required: - status - invitation participation: type: - object - 'null' description: Null when no applicable participation record exists. properties: decision: type: - string - 'null' enum: - opt_in - opt_out - null decidedAt: type: - string - 'null' format: date-time required: - decision - decidedAt coverage: type: - object - 'null' description: Null when no applicable coverage record exists. properties: status: type: string enum: - enrolled - enrolled_not_paying - awaiting_coverage - waived - terminated startsAt: type: string format: date endsAt: type: - string - 'null' format: date planTier: type: string required: - status - startsAt - endsAt - planTier createdAt: type: string format: date-time updatedAt: type: string format: date-time description: >- Employee object. Participation and coverage are separate from membership. required: - id - companyId - personId - externalIds - demographics - contact - membership - participation - coverage - createdAt - updatedAt responses: InvalidInput: description: >- Invalid search, query, or path input. A message may name an unsupported search field or external ID system, or a text filter over 100 characters. content: application/json: schema: type: object properties: error: type: string enum: - invalid_input message: type: string description: >- Names the unsupported search field or externalIdSystems value, or the text filter over 100 characters, when applicable. required: - error additionalProperties: false example: error: invalid_input InvalidApiKey: description: Missing or invalid partner API key. content: application/json: schema: type: object properties: error: type: string enum: - invalid_api_key required: - error additionalProperties: false example: error: invalid_api_key Forbidden: description: >- Operation or company access is not permitted, including a requested archived company. content: application/json: schema: type: object properties: error: type: string enum: - forbidden required: - error additionalProperties: false example: error: forbidden RateLimited: description: Partner API key request allowance is exhausted. content: application/json: schema: type: object properties: error: type: string enum: - rate_limited required: - error additionalProperties: false example: error: rate_limited InternalError: description: The service could not complete the request. content: application/json: schema: type: object properties: error: type: string enum: - internal_error required: - error additionalProperties: false example: error: internal_error securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.