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

> For finding people across authorized employments.

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](/search-employees).


## OpenAPI

````yaml openapi.json POST /v1/persons/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/persons/search:
    post:
      summary: Search persons
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                companyId:
                  type: string
                  description: Optional authorized company filter.
                  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 on an authorized employment.
                  minLength: 1
                lastName:
                  type: string
                  description: Case-insensitive partial match on an authorized employment.
                  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 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:
                limit: 50
                offset: 0
        description: JSON request body. 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 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
      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: 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
  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.