> ## Documentation Index > Fetch the complete documentation index at: https://docs.partner-api.tryrima.com/llms.txt > Use this file to discover all available pages before exploring further. # Search persons > Draft contract for finding people across authorized employments. **Coming soon — unavailable in sandbox and production.** The code sample uses the current Partner API host for illustration; the final hostname and contract are undecided. Do not send requests to this route. Filters would combine with AND. Company, name, and phone filters must match the same authorized employment. They would select people, not trim a matching person's returned `employments` array. The proposal returns 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`. It paginates people rather than employments and sorts by Person `createdAt` then `id`. Employee records without a Person link remain available through [Search employees](/coming-soon/search-employees). Response-size limits for complete employment arrays remain undecided. ## OpenAPI ````yaml POST /v1/persons/search openapi: 3.1.0 info: title: Rima Partner API proposed endpoints version: draft description: Documentation preview only. These operations are not implemented. servers: - url: https://partner-api.tryrima.com description: Rima (route not available) security: [] paths: /v1/persons/search: post: summary: Search persons description: Proposed endpoint. Not available in any environment. requestBody: required: true content: application/json: schema: type: object properties: companyId: type: string description: Optional authorized company filter. phone: type: string description: >- Match on an authorized employment after normalization; accepted formats undecided. firstName: type: string description: >- Proposed case-insensitive partial match on an authorized employment. lastName: type: string description: >- Proposed case-insensitive partial match on an authorized employment. personId: type: string description: Exact Person UUID match. format: uuid externalIdSystems: type: array description: Selects returned external IDs; does not filter records. items: type: string createdFrom: type: string description: Inclusive Person creation-time lower bound. format: date-time createdBefore: type: string description: Exclusive Person creation-time upper bound. format: date-time limit: type: integer minimum: 1 maximum: 100 default: 50 offset: type: integer minimum: 0 default: 0 example: companyId: company_example limit: 50 offset: 0 responses: '200': description: Proposed 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-01T00:00:00Z' endsAt: null 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 security: - bearerAuth: [] components: schemas: Person: type: object properties: id: type: string description: Person UUID. format: uuid employments: type: array description: Complete Employee objects in authorized companies. items: $ref: '#/components/schemas/Employee' createdAt: type: string format: date-time updatedAt: type: string description: Person-row timestamp; not a watermark for nested employment data. format: date-time 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: Linked Person UUID; null when identity is unresolved. format: uuid externalIds: type: array description: Identifiers in external systems. items: type: object properties: system: type: string system_id: type: string demographics: type: object properties: firstName: type: string lastName: type: string dateOfBirth: type: string format: date gender: type: - string - 'null' contact: type: object properties: email: type: string phone: type: string address: type: object properties: line1: type: string line2: type: - string - 'null' city: type: string state: type: string postalCode: type: string membership: type: object properties: status: type: string description: >- 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 participation: type: - object - 'null' description: >- Null when no applicable participation record exists; selection across multiple plan programs is pending. properties: decision: type: - string - 'null' enum: - opt_in - opt_out - null decidedAt: type: - string - 'null' format: date-time coverage: type: - object - 'null' description: >- Null when no applicable coverage record exists; selection across multiple plan programs is pending. properties: status: type: string enum: - enrolled - enrolled_not_paying - awaiting_coverage - waived - terminated startsAt: type: string format: date-time endsAt: type: - string - 'null' format: date-time planTier: type: - string - 'null' createdAt: type: string format: date-time updatedAt: type: string format: date-time description: >- Draft shared Employee object. Participation and coverage are separate from membership; record selection across multiple plan programs is pending. securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.