> ## 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 employees > Draft contract for finding employee records in an authorized company. **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. Search filters would combine with AND. `externalIdSystems` would select the external IDs returned in each Employee object; it would not filter records. The proposal includes terminated records, preserves duplicate employee records, and sorts by `createdAt` then `id`. Pagination reads live data. Full Social Security numbers would not be returned. Each Employee object includes top-level `participation` and `coverage` fields. Each is `null` when no applicable record exists. Phone normalization formats, name matching, and selection across multiple plan programs remain undecided. ## OpenAPI ````yaml POST /v1/employees/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/employees/search: post: summary: Search employees description: Proposed endpoint. Not available in any environment. requestBody: required: true content: application/json: schema: type: object properties: companyId: type: string description: Required authorized company ID. phone: type: string description: Exact match after normalization; accepted formats undecided. firstName: type: string description: Proposed case-insensitive partial match. lastName: type: string description: Proposed case-insensitive partial match. 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 creation-time lower bound. format: date-time createdBefore: type: string description: Exclusive creation-time upper bound. format: date-time limit: type: integer minimum: 1 maximum: 100 default: 50 offset: type: integer minimum: 0 default: 0 required: - companyId example: companyId: company_example limit: 50 offset: 0 responses: '200': description: Proposed employee search results. content: application/json: schema: type: object properties: asOf: type: string format: date-time employees: type: array items: $ref: '#/components/schemas/Employee' pagination: $ref: '#/components/schemas/Pagination' required: - asOf - employees - pagination examples: example: value: asOf: '2026-10-13T15:00:00Z' employees: - 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' pagination: limit: 50 offset: 0 total: 1 security: - bearerAuth: [] components: schemas: 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. Pagination: type: object properties: limit: type: integer offset: type: integer total: type: integer required: - limit - offset - total securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.