Remote Employments API

openapi: 3.0.0
info:
  title: Remote Address Details Employments API
  version: 0.1.0
servers:
- url: https://gateway.remote.com/
  variables: {}
- url: https://gateway.remote-sandbox.com/
  variables: {}
security:
- OAuth2: []
tags:
- name: Employments
paths:
  /v2/employments/{employment_id}/pricing-plan-details:
    put:
      callbacks: {}
      deprecated: false
      description: 'Updates the pricing plan for an employment. The frequency determines how often Remote bills the

        employer for management fees. Annual billing typically offers a discount.



        ## Scopes


        | Category | Read only Scope | Write only Scope (read access implicit) |

        |---|---|---|

        | Manage employments (`employments`) | - | Manage employments (`employment:write`) |

        '
      operationId: put_v2_employments_employment_id_pricing-plan-details
      parameters:
      - description: Employment ID
        example: 93t3j-employment-id-9suej43
        in: path
        name: employment_id
        required: true
        schema:
          type: string
      - description: Version of the pricing_plan_details form schema
        example: 1
        in: query
        name: pricing_plan_details_json_schema_version
        required: false
        schema:
          default: latest
          oneOf:
          - description: Specific version number
            minimum: 1
            type: integer
          - description: Use latest version
            enum:
            - latest
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmploymentPricingPlanDetailsParams'
        description: Employment pricing plan details params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmploymentDetailsOnlyResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Unprocessable Entity
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - employment:write
        - employments
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - employment:write
        - employments
        - all:write
      summary: Update pricing plan details
      tags:
      - Employments
  /v1/cancel-onboarding/{employment_id}:
    post:
      callbacks: {}
      deprecated: false
      description: 'Cancel onboarding.


        Requirements for the cancellation to succeed:


        * Employment has to be in `invited`, `created`, `created_awaiting_reserve`, `created_reserve_paid`, `pre_hire` status

        * Employee must not have signed the employment contract



        ## Scopes


        | Category | Read only Scope | Write only Scope (read access implicit) |

        |---|---|---|

        | Manage employments (`employments`) | - | Manage onboarding (`onboarding:write`) |

        '
      operationId: post_v1_cancel-onboarding_employment_id
      parameters:
      - description: Employment ID
        example: 31b8e49b-aa1c-47af-849c-3d0a53e20e0d
        in: path
        name: employment_id
        required: true
        schema:
          type: string
      - description: 'Whether the request should be performed async

          '
        example: true
        in: query
        name: async
        required: false
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: Bad Request
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Unprocessable Entity
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - onboarding:write
        - employments
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - onboarding:write
        - employments
        - all:write
      summary: Cancel onboarding
      tags:
      - Employments
  /v2/employments/{employment_id}/address-details:
    put:
      callbacks: {}
      deprecated: false
      description: 'Updates employment''s address details.


        This endpoint requires and returns country-specific data. The exact required and returned fields will

        vary depending on which country the employment is in. To see the list of parameters for each country,

        see the **Show form schema** endpoint under the [Countries](#tag/Countries) category.


        Please note that the compliance requirements for each country are subject to change according to local

        laws. Given its continual updates, using Remote''s [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) should be considered in order to avoid

        compliance issues and to have the latest version of a country requirements.


        If you are using this endpoint to build an integration, make sure you are dynamically collecting or

        displaying the latest parameters for each country by querying the _"Show form schema"_ endpoint.


        For more information on JSON Schemas, see the **How JSON Schemas work** documentation.


        To learn how you can dynamically generate forms to display in your UI, see the documentation for

        the [json-schema-form](https://developer.remote.com/docs/how-json-schemas-form) tool.




        ## Scopes


        | Category | Read only Scope | Write only Scope (read access implicit) |

        |---|---|---|

        | Manage employments (`employments`) | - | Manage employments (`employment:write`) |

        '
      operationId: put_v2_employments_employment_id_address-details
      parameters:
      - description: Employment ID
        example: 93t3j-employment-id-9suej43
        in: path
        name: employment_id
        required: true
        schema:
          type: string
      - description: Version of the address_details form schema
        example: 1
        in: query
        name: address_details_json_schema_version
        required: false
        schema:
          default: latest
          oneOf:
          - description: Specific version number
            minimum: 1
            type: integer
          - description: Use latest version
            enum:
            - latest
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmploymentAddressDetailsParams'
        description: Employment address details params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmploymentDetailsOnlyResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Unprocessable Entity
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - employment:write
        - employments
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - employment:write
        - employments
        - all:write
      summary: Update address details
      tags:
      - Employments
  /v1/employments:
    get:
      callbacks: {}
      deprecated: false
      description: 'Lists all employments, except for the deleted ones.


        This endpoint requires and returns country-specific data. The exact required and returned fields will

        vary depending on which country the employment is in. To see the list of parameters for each country,

        see the **Show form schema** endpoint under the [Countries](#tag/Countries) category.


        Please note that the compliance requirements for each country are subject to change according to local

        laws. Given its continual updates, using Remote''s [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) should be considered in order to avoid

        compliance issues and to have the latest version of a country requirements.


        If you are using this endpoint to build an integration, make sure you are dynamically collecting or

        displaying the latest parameters for each country by querying the _"Show form schema"_ endpoint.


        For more information on JSON Schemas, see the **How JSON Schemas work** documentation.


        To learn how you can dynamically generate forms to display in your UI, see the documentation for

        the [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) tool.


        '
      operationId: get_v1_employments
      parameters:
      - description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.


          The refresh token needs to have been obtained through the Authorization Code flow.

          '
        example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
        in: header
        name: Authorization
        required: true
        schema:
          type: string
      - description: Company ID
        example: 93t3j-company-id-9suej43
        in: query
        name: company_id
        required: false
        schema:
          type: string
      - description: Filters the results by employments whose login email matches the value
        example: anna@example.com
        in: query
        name: email
        required: false
        schema:
          type: string
      - description: 'Filters the results by employments whose status matches the value.

          Supports multiple values separated by commas.

          Also supports the value `incomplete` to get all employments that are not onboarded yet.

          '
        in: query
        name: status
        required: false
        schema:
          type: string
      - description: Filters the results by employments whose employment product type matches the value
        example: contractor
        in: query
        name: employment_type
        required: false
        schema:
          type: string
      - description: 'Filters the results by employments whose employment model matches the value.

          Possible values: `global_payroll`, `peo`, `eor`

          '
        example: global_payroll
        in: query
        name: employment_model
        required: false
        schema:
          enum:
          - global_payroll
          - peo
          - eor
          type: string
      - description: Filters the results by the employment's short ID. Returns at most one result.
        example: aB1cD2
        in: query
        name: short_id
        required: false
        schema:
          type: string
      - description: Starts fetching records after the given page
        example: 1
        in: query
        name: page
        required: false
        schema:
          default: 1
          minimum: 1
          type: integer
      - description: Number of items per page
        example: 20
        in: query
        name: page_size
        required: false
        schema:
          default: 20
          maximum: 100
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEmploymentsResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Unprocessable Entity
      summary: List employments
      tags:
      - Employments
    post:
      callbacks: {}
      deprecated: false
      description: 'Creates an employment. We support creating employees and contractors.


        ## Global Payroll Employees


        To create a Global Payroll employee, pass `global_payroll_employee` as the `type` parameter,

        and provide the id of the specific legal entity that the employee will be engaged by and billed to as the `engaged_by_legal_entity_id` parameter.


        ## HRIS Employees


        To create a HRIS employee, pass `hris` as the `type` parameter.


        This endpoint requires and returns country-specific data. The exact required and returned fields will

        vary depending on which country the employment is in. To see the list of parameters for each country,

        see the **Show form schema** endpoint under the [Countries](#tag/Countries) category.


        Please note that the compliance requirements for each country are subject to change according to local

        laws. Given its continual updates, using Remote''s [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) should be considered in order to avoid

        compliance issues and to have the latest version of a country requirements.


        If you are using this endpoint to build an integration, make sure you are dynamically collecting or

        displaying the latest parameters for each country by querying the _"Show form schema"_ endpoint.


        For more information on JSON Schemas, see the **How JSON Schemas work** documentation.


        To learn how you can dynamically generate forms to display in your UI, see the documentation for

        the [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) tool.




        ## Scopes


        | Category | Read only Scope | Write only Scope (read access implicit) |

        |---|---|---|

        | Manage employments (`employments`) | - | Manage employments (`employment:write`) |

        '
      operationId: post_v1_employments
      parameters:
      - description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.


          The refresh token needs to have been obtained through the Authorization Code flow.

          '
        example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
        in: header
        name: Authorization
        required: true
        schema:
          type: string
      - description: Version of the form schema
        example: 1
        in: query
        name: json_schema_version
        required: false
        schema:
          default: latest
          oneOf:
          - description: Specific version number
            minimum: 1
            type: integer
          - description: Use latest version
            enum:
            - latest
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmploymentCreateParams'
        description: Employment params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmploymentCreationResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Unprocessable Entity
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - employment:write
        - employments
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - employment:write
        - employments
        - all:write
      summary: Create employment
      tags:
      - Employments
  /v1/employee/bank-account:
    get:
      callbacks: {}
      deprecated: false
      description: 'Returns the authenticated employee''s bank account details.


        This endpoint requires and returns country-specific data. The exact fields vary depending on which

        country the authenticated employee''s employment is in. Query the

        [Show form schema](#tag/Countries/operation/get_show_form_country) endpoint with `bank_account_details`

        as the form name to discover the schema for a given country.




        ## Scopes


        | Category | Read only Scope | Write only Scope (read access implicit) |

        |---|---|---|

        | Manage employments (`employments`) | View bank accounts (`bank_account:read`) | Manage bank accounts (`bank_account:write`) |

        '
      operationId: get_v1_employee_bank-account
      parameters:
      - description: Version of the bank_account_details form schema
        example: 1
        in: query
        name: bank_account_details_json_schema_version
        required: false
        schema:
          default: latest
          oneOf:
          - description: Specific version number
            minimum: 1
            type: integer
          - description: Use latest version
            enum:
            - latest
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmploymentDetailsOnlyResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Unprocessable Entity
      security:
      - OAuth2Assertion:
        - bank_account:read
        - bank_account:write
        - employments
        - all:write
        - all:read
      summary: Show employee bank account
      tags:
      - Employments
    put:
      callbacks: {}
      deprecated: false
      description: 'Upserts the authenticated employee''s bank account details.


        This endpoint requires and returns country-specific data. The exact fields vary depending on which

        country the authenticated employee''s employment is in. Query the

        [Show form schema](#tag/Countries/operation/get_show_form_country) endpoint with `bank_account_details`

        as the form name to discover the schema for a given country.




        ## Scopes


        | Category | Read only Scope | Write only Scope (read access implicit) |

        |---|---|---|

        | Manage employments (`employments`) | - | Manage bank accounts (`bank_account:write`) |

        '
      operationId: put_v1_employee_bank-account
      parameters:
      - description: Version of the bank_account_details form schema
        example: 1
        in: query
        name: bank_account_details_json_schema_version
        required: false
        schema:
          default: latest
          oneOf:
          - description: Specific version number
            minimum: 1
            type: integer
          - description: Use latest version
            enum:
            - latest
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmploymentBankAccountDetailsParams'
        description: Employee bank account details params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmploymentDetailsOnlyResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Unprocessable Entity
      security:
      - OAuth2Assertion:
        - bank_account:write
        - employments
        - all:write
      summary: Update employee bank account
      tags:
      - Employments
  /v2/employments/{employment_id}/engagement-agreement-details:
    get:
      callbacks: {}
      deprecated: false
      description: 'Returns the engagement agreement details for an employment.


        ## Scopes


        | Category | Read only Scope | Write only Scope (read access implicit) |

        |---|---|---|

        | Manage employments (`employments`) | View employments (`employment:read`) | Manage employments (`employment:write`) |

        '
      operationId: get_v2_employments_employment_id_engagement-agreement-details
      parameters:
      - description: Employment ID
        example: 93t3j-employment-id-9suej43
        in: path
        name: employment_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmploymentEngagementAgreementDetailsResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Unprocessable Entity
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - employment:read
        - employment:write
        - employments
        - all:write
        - all:read
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - employment:read
        - employment:write
        - employments
        - all:write
        - all:read
      summary: Get engagement agreement details
      tags:
      - Employments
    post:
      callbacks: {}
      deprecated: false
      description: 'Creates or updates the engagement agreement details for an employment.


        This endpoint requires country-specific data. The exact required fields will vary depending on

        which country the employment is in. To see the list of parameters for each country, see the

        **Show form schema** endpoint under the [Countries](#tag/Countries) category.


        Please note that compliance requirements for each country are subject to change according to local laws.

        Using Remote''s [json-schema-form](https://developer.remote.com/docs/how-json-schemas-work) is recommended

        to avoid compliance issues and to have the latest version of a country''s requirements.




        ## Scopes


        | Category | Read only Scope | Write only Scope (read access implicit) |

        |---|---|---|

        | Manage employments (`employments`) | - | Manage employments (`employment:write`) |

        '
      operationId: post_v2_employments_employment_id_engagement-agreement-details
      parameters:
      - description: Employment ID
        example: 93t3j-employment-id-9suej43
        in: path
        name: employment_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmploymentEngagementAgreementDetailsParams'
        description: Employment engagement agreement details params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Unprocessable Entity
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - employment:write
        - employments
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - employment:write
        - employments
        - all:write
      summary: Upsert engagement agreement details
      tags:
      - Employments
  /v1/employee/documents/{id}:
    get:
      callbacks: {}
      deprecated: false
      description: '## Scopes


        | Category | Read only Scope | Write only Scope (read access implicit) |

        |---|---|---|

        | Manage employment documents (`employment_documents`) | View documents (`document:read`) | Manage documents (`document:write`) |

        '
      operationId: get_v1_employee_documents_id
      parameters:
      - description: Document ID
        example: 93t3j-file-id-9suej43
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadDocumentResponse'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        '422':
          conten

# --- truncated at 32 KB (402 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-employments-api-openapi.yml