openapi: 3.0.0
info:
  title: Employer Search API
  description: Dedicated endpoint for free-text search implementations.
  version: 1.0.0
security:
  - basicAuth: []
paths:
  /v2/employer-search:
    get:
      summary: List all employers
      description: >-
        Returns a paginated list of all Item objects, representing the most
        relevant search results.
      operationId: listEmployers
      parameters:
        - name: q
          in: query
          description: Free-text search filter.
          required: false
          schema:
            type: string
        - name: kind
          in: query
          description: Filter by `kind` value.
          required: false
          schema:
            type: string
        - name: mapping_status
          in: query
          description: >
            Filter by `mapping_status` value.


            Multiple `mapping_status` values can also be searched at once using
            either method:


            1. `/v2/items?mapping_status=verified,mapped`

            2. `/v2/items?mapping_status=verified&mapping_status=mapped`
          required: false
          schema:
            type: string
        - name: status
          in: query
          description: >
            Filter by `status` value.


            Multiple `status` values can also be searched at once using either
            method:


            1. `/v2/items?status=healthy,issues`

            2. `/v2/items?status=healthy&status=issues`


            Filtering by both `healthy` and `issues` will return all Items that
            currently support new payroll connections.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: >-
            Number of Item objects returned [per
            page](/api-guide/overview#pagination). Default: 10. Maximum: 200.
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 200
        - in: query
          name: cursor
          schema:
            type: string
          description: >-
            The URL returned in `next` or `previous` used to retrieve another
            [page](/api-guide/overview#pagination) of results.
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    format: uri
                    nullable: true
                    description: URL for the next page of results, if available.
                  previous:
                    type: string
                    format: uri
                    nullable: true
                    description: URL for the previous page of results, if available.
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Employer'
              example:
                next: >-
                  https://api-sandbox.argyle.com/v2/employer-search?cursor=ZXhhbXBsZV9jdXJzb3I
                previous: null
                results:
                  - id: item_000000002
                    name: Bullseye
                    logo_url: argyle.com/image-holdings
                    kind: employer
                    mapping_status: verified
                    status: unavailable
                  - id: item_000000003
                    name: Triple
                    logo_url: argyle.com/image-holdings
                    kind: platform
                    mapping_status: mapped
                    status: healthy
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Username = api_key_id, Password = api_key_secret
  schemas:
    Employer:
      type: object
      example:
        id: item_000000003
        name: GigAndGo
        logo_url: argyle.com/image-holdings
        kind: gig
        mapping_status: verified
        status: healthy
      properties:
        id:
          type: string
          description: >-
            Unique ID of the [Item](/api-reference/items). ID format —
            `item_123456789`
        name:
          type: string
          description: Name of the Item.
        logo_url:
          type: string
          description: URL location of the Item's logo image file.
        kind:
          type: string
          enum:
            - employer
            - gig
            - platform
            - benefits
          description: |
            Type of Item.
            - `employer` — individual employer
            - `gig` — gig platform
            - `platform` — payroll provider platform
            - `benefits` — government benefits
        mapping_status:
          type: string
          enum:
            - verified
            - mapped
            - unmapped
          description: >
            Verification status of the Item.

            - `verified` — The payroll system associated with the Item is known,
            and the Item has previously experienced a successful connection that
            returned paystub data.


            - `mapped` — The payroll system associated with the Item is known,
            but the Item is awaiting a successful connection.


            - `unmapped` — The payroll system associated with this Item is not
            yet known. If an unmapped Item is selected in Link, the user will be
            given the option to search for the relevant payroll system and
            attempt to connect using their login credentials.


            ![](/images/argyle-guides/api-ref/items/1-mapping-status.png)
        status:
          type: string
          enum:
            - healthy
            - issues
            - unavailable
          description: >
            Health status of the Item.


            - `healthy` — Normal service.

            - `issues` — Impacted service. New account connections still
            supported.

            - `unavailable` — Impacted service. New account connections not
            supported. [Ongoing refresh](/overview/ongoing-refresh) paused.