openapi: 3.1.0
info:
  title: Justworks Members API
  description: |
    Read employee, contractor, and member information from the Justworks
    Partner API. Provides access to member profiles, employment history,
    pay history, custom field values, and U.S. tax identifiers.

    Justworks operates a Professional Employer Organization (PEO) and HR
    platform; the Members API is the canonical source of truth for the
    workforce a partner is integrating against.
  version: '2026-05-25'
  contact:
    name: Justworks Partner Support
    url: https://public-api.justworks.com/v1/docs

servers:
  - url: https://public-api.justworks.com
    description: Production Server

security:
  - OAuth2: []

tags:
  - name: Members
    description: Read access to Justworks member records, custom fields, and tax IDs

paths:
  /v1/members:
    get:
      summary: Justworks List Members
      description: |
        List members of the company. Supports cursor pagination, status
        filtering (active or terminated), and updated_at filtering with
        comparison operators.
      operationId: listMembers
      tags:
        - Members
      parameters:
        - name: cursor
          in: query
          description: Opaque pagination cursor returned by the previous response
          schema:
            type: string
        - name: limit
          in: query
          description: Page size between 1 and 100
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
        - name: status
          in: query
          description: Filter by employment status
          schema:
            type: string
            enum:
              - active
              - terminated
        - name: updated_at
          in: query
          description: |
            ISO-8601 timestamp filter. Append an operator suffix to compare:
            _gt, _gte, _lt, _lte, _ne.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: A paginated list of members
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /v1/members/{member_id}:
    get:
      summary: Justworks Get Member
      description: Retrieve a single Justworks member by id.
      operationId: getMember
      tags:
        - Members
      parameters:
        - $ref: '#/components/parameters/MemberId'
      responses:
        '200':
          description: A single Justworks member
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '404':
          $ref: '#/components/responses/NotFound'

  /v1/members/{member_id}/custom-field-values:
    get:
      summary: Justworks List Member Custom Field Values
      description: List custom field values associated with a member.
      operationId: listMemberCustomFieldValues
      tags:
        - Members
      parameters:
        - $ref: '#/components/parameters/MemberId'
      responses:
        '200':
          description: Member custom field values
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomFieldValue'

  /v1/members/{member_id}/tax-id:
    get:
      summary: Justworks Get Member Tax ID
      description: |
        Retrieve a member's U.S. Social Security Number. Restricted to
        domestic members; returns 400 for international contractors and
        404 for employer-of-record and international employees.
      operationId: getMemberTaxId
      tags:
        - Members
      parameters:
        - $ref: '#/components/parameters/MemberId'
      responses:
        '200':
          description: Tax identifier wrapped by jurisdiction
          content:
            application/json:
              schema:
                type: object
                properties:
                  US:
                    type: object
                    properties:
                      ssn:
                        type: string
        '400':
          description: Member is an international contractor
        '404':
          description: Member is an EOR or international employee

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://secure.justworks.com/oauth/authorize
          tokenUrl: https://public-api.justworks.com/oauth/token
          refreshUrl: https://public-api.justworks.com/oauth/token
          scopes:
            member.basic:read: Read basic member profile fields
            member.detail:read: Read detailed member profile including history
            member.employment:read: Read employment records
            member.pay:read: Read pay history
            member.tax_id:read: Read U.S. tax identifier (SSN)
            member.dob:read: Read date of birth
            member.sex:read: Read sex assigned at birth

  parameters:
    MemberId:
      name: member_id
      in: path
      required: true
      description: Justworks member identifier
      schema:
        type: string

  responses:
    Unauthorized:
      description: Missing or invalid OAuth token
    Forbidden:
      description: Token lacks the required scope
    NotFound:
      description: Resource not found

  schemas:
    MemberList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Member'
        next_cursor:
          type: string
          nullable: true

    Member:
      type: object
      properties:
        id:
          type: string
        company_id:
          type: string
        work_id:
          type: string
        name:
          $ref: '#/components/schemas/MemberName'
        active:
          type: boolean
        employment_location_type:
          type: string
        type:
          type: string
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        emails:
          type: array
          items:
            type: object
        employment_history:
          type: array
          items:
            type: object
        pay_history:
          type: array
          items:
            type: object
        phones:
          type: array
          items:
            type: object
        current_employment:
          type: object
        current_pay:
          type: object
        current_pay_frequency:
          type: string
        date_added_to_justworks:
          type: string
          format: date
        date_of_birth:
          type: string
          format: date
        department:
          type: object
        employment_start_date:
          type: string
          format: date
        employment_termination_date:
          type: string
          format: date
          nullable: true
        job_title:
          type: string
        manager:
          type: object
        office:
          type: object
        partner_settings:
          type: object
        sex_assigned_at_birth:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    MemberName:
      type: object
      properties:
        family_name:
          type: string
        given_name:
          type: string
        full_preferred_name:
          type: string
        preferred_name:
          type: string
        additional_names:
          type: array
          items:
            type: string

    Address:
      type: object
      properties:
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        state:
          type: string
        postal_code:
          type: string
        country:
          type: string

    CustomFieldValue:
      type: object
      properties:
        id:
          type: string
        values:
          type: array
          items:
            type: string