> ## 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

> For finding employee records in an authorized company.

Search filters combine with AND. A nonempty `companyId` is required. Supplied first and last names 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`; it selects returned external IDs without filtering records.

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`. A company outside the key's policy returns `403 forbidden`.

Results include terminated records, preserve duplicate employee records, and sort by `createdAt` then `id`. Pagination reads live data. Full Social Security numbers are not returned.

Each Employee object includes top-level `participation` and `coverage` fields. Each is `null` when no applicable record exists.


## OpenAPI

````yaml openapi.json POST /v1/employees/search
openapi: 3.1.0
info:
  title: Rima Partner API
  version: 0.0.1
  description: >-
    Use `https://partner-api.tryrima.com` for the Rima Partner API.


    Send requests from your backend with `Authorization: Bearer <key>`. 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://partner-api.tryrima.com
    description: Rima
security: []
paths:
  /v1/employees/search:
    post:
      summary: Search employees
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                companyId:
                  type: string
                  description: Required authorized company ID.
                  minLength: 1
                phone:
                  type: string
                  description: >-
                    Digits must normalize to exactly 10; an optional leading 1
                    is removed.
                firstName:
                  type: string
                  description: Case-insensitive partial match.
                  minLength: 1
                lastName:
                  type: string
                  description: Case-insensitive partial match.
                  minLength: 1
                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
                    enum:
                      - payroll_system
                      - hhaexchange
                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
        description: JSON request body. Bodies over 1 MiB return 400 invalid_input.
      responses:
        '200':
          description: 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-01'
                          endsAt: '2026-12-31'
                          planTier: example_tier
                        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:
    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
                enum:
                  - payroll_system
                  - hhaexchange
              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: >-
                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
    Pagination:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer
      required:
        - limit
        - offset
        - total
  responses:
    InvalidInput:
      description: >-
        Invalid search, query, or path input. Unsupported external ID systems
        include a message naming the value.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                enum:
                  - invalid_input
              message:
                type: string
                description: Names the unsupported externalIdSystems value 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.
      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.