Justworks Members API

openapi: 3.1.0
info:
  title: Justworks Company Members API
  description: 'Read company-level data from the Justworks Partner API including

    company identity, bank account on file, verified business information,

    custom field definitions, and operating jurisdictions.

    '
  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:
  responses:
    Forbidden:
      description: Token lacks the required scope
    NotFound:
      description: Resource not found
    Unauthorized:
      description: Missing or invalid OAuth token
  schemas:
    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
    CustomFieldValue:
      type: object
      properties:
        id:
          type: string
        values:
          type: array
          items:
            type: string
    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
    MemberList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Member'
        next_cursor:
          type: string
          nullable: true
  parameters:
    MemberId:
      name: member_id
      in: path
      required: true
      description: Justworks member identifier
      schema:
        type: string
  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:
            company.basic:read: Read basic company data
            company.detail:read: Read detailed company data
            company.bank_account:read: Read company bank account on file