Remote Terminations API

openapi: 3.0.0
info:
  title: Remote Address Details Terminations API
  version: 0.1.0
servers:
- url: https://gateway.remote.com/
  variables: {}
- url: https://gateway.remote-sandbox.com/
  variables: {}
security:
- OAuth2: []
tags:
- name: Terminations
paths:
  /v1/offboardings:
    get:
      callbacks: {}
      description: 'Lists Offboarding requests.


        ## Scopes


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

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

        | Manage employments (`employments`) | View offboarding requests (`offboarding:read`) | Manage offboarding (`offboarding:write`) |

        '
      operationId: get_v1_offboardings
      parameters:
      - description: Filter by Employment ID
        example: 93t3j-employment-id-9suej43
        in: query
        name: employment_id
        required: false
        schema:
          type: string
      - description: Filter by offboarding type
        example: paid
        in: query
        name: type
        required: false
        schema:
          type: string
      - description: 'By default, the results do not include confidential termination requests.

          Send `include_confidential=true` to include confidential requests in the response.

          '
        example: 'true'
        in: query
        name: include_confidential
        required: false
        schema:
          type: string
      - description: Starts fetching records after the given page
        example: 1
        in: query
        name: page
        required: false
        schema:
          type: integer
      - description: Change the amount of records returned per page, defaults to 20, limited to 100
        example: 30
        in: query
        name: page_size
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOffboardingResponse'
          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
        '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: Too many requests
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - offboarding:read
        - offboarding:write
        - employments
        - all:write
        - all:read
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - offboarding:read
        - offboarding:write
        - employments
        - all:write
        - all:read
      summary: List Offboarding
      tags:
      - Terminations
    post:
      callbacks: {}
      description: 'Creates an Offboarding request



        ## Scopes


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

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

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

        '
      operationId: post_v1_offboardings
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOffboardingParams'
        description: Offboarding
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OffboardingResponse'
          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
        '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: Too many requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
          description: Internal Server Error
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - offboarding:write
        - employments
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - offboarding:write
        - employments
        - all:write
      summary: Create Offboarding
      tags:
      - Terminations
  /v2/offboardings:
    get:
      callbacks: {}
      description: 'Lists offboardings for a company.



        ## Scopes


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

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

        | Manage employments (`employments`) | View offboarding requests (`offboarding:read`) | Manage offboarding (`offboarding:write`) |

        '
      operationId: get_v2_offboardings
      parameters:
      - description: Filter by Employment ID
        example: 93t3j-employment-id-9suej43
        in: query
        name: employment_id
        required: false
        schema:
          type: string
      - description: Filter by offboarding type.
        example: termination
        in: query
        name: type
        required: false
        schema:
          enum:
          - termination
          - resignation
          - cancellation
          - relocation
          - transfer
          - conversion
          type: string
      - description: 'By default, the results do not include confidential termination requests.

          Send `include_confidential=true` to include confidential requests in the response.

          '
        example: true
        in: query
        name: include_confidential
        required: false
        schema:
          type: boolean
      - description: Starts fetching records after the given page
        example: 1
        in: query
        name: page
        required: false
        schema:
          type: integer
      - description: Change the amount of records returned per page, defaults to 20, limited to 100
        example: 30
        in: query
        name: page_size
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ListOffboardingResponse'
          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
        '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: Too many requests
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - offboarding:read
        - offboarding:write
        - employments
        - all:write
        - all:read
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - offboarding:read
        - offboarding:write
        - employments
        - all:write
        - all:read
      summary: List Offboardings (v2)
      tags:
      - Terminations
  /v2/offboardings/{id}:
    get:
      callbacks: {}
      description: 'Returns a single offboarding by its ID.



        ## Scopes


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

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

        | Manage employments (`employments`) | View offboarding requests (`offboarding:read`) | Manage offboarding (`offboarding:write`) |

        '
      operationId: get_v2_offboardings_id
      parameters:
      - description: Offboarding ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2OffboardingResponse'
          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
        '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: Too many requests
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - offboarding:read
        - offboarding:write
        - employments
        - all:write
        - all:read
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - offboarding:read
        - offboarding:write
        - employments
        - all:write
        - all:read
      summary: Show Offboarding (v2)
      tags:
      - Terminations
  /v1/offboardings/employments/{employment_id}:
    get:
      callbacks: {}
      description: 'Lists Offboarding requests for a specific employment.


        ## Scopes


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

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

        | Manage employments (`employments`) | View offboarding requests (`offboarding:read`) | Manage offboarding (`offboarding:write`) |

        '
      operationId: get_v1_offboardings_employments_employment_id
      parameters:
      - description: Employment ID
        in: path
        name: employment_id
        required: true
        schema:
          type: string
        x-resource-type: employment
      - description: Starts fetching records after the given page
        example: 1
        in: query
        name: page
        required: false
        schema:
          type: integer
      - description: Change the amount of records returned per page, defaults to 20, limited to 100
        example: 30
        in: query
        name: page_size
        required: false
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOffboardingResponse'
          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
        '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: Too many requests
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - offboarding:read
        - offboarding:write
        - employments
        - all:write
        - all:read
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - offboarding:read
        - offboarding:write
        - employments
        - all:write
        - all:read
      summary: List Offboardings for Employment
      tags:
      - Terminations
  /v1/offboardings/{id}:
    get:
      callbacks: {}
      description: 'Shows an Offboarding request.


        ## Scopes


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

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

        | Manage employments (`employments`) | View offboarding requests (`offboarding:read`) | Manage offboarding (`offboarding:write`) |

        '
      operationId: get_v1_offboardings_id
      parameters:
      - description: Offboarding request ID
        in: path
        name: id
        required: true
        schema:
          type: string
        x-safe: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OffboardingResponse'
          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
        '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: Too many requests
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - offboarding:read
        - offboarding:write
        - employments
        - all:write
        - all:read
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - offboarding:read
        - offboarding:write
        - employments
        - all:write
        - all:read
      summary: Show Offboarding
      tags:
      - Terminations
components:
  schemas:
    ParameterError:
      example:
        code: invalid_param
        message: Invalid parameter
        param: employment_id
      properties:
        code:
          description: An error code that describes the nature of the error.
          type: string
        message:
          description: A developer friendly error message that gives details on what the error was and how it may be remedied.
          type: string
        param:
          description: The parameter that lead to the error message.
          type: string
      required:
      - code
      - message
      - param
      title: ParameterError
      type: object
    TerminationDetailsParams:
      example:
        confidential: false
        proposed_termination_date: '2024-10-30'
        reason_description: They had some performance issues and mismatched expectations.
        risk_assessment_reasons:
        - pregnant_or_breastfeeding
        - family_leave
        termination_reason: performance
        will_challenge_termination: true
      properties:
        acknowledge_termination_procedure:
          description: Whether the employer acknowledges and agrees to follow Remote's termination procedure for this jurisdiction.
          nullable: true
          type: boolean
        additional_comments:
          description: Additional details regarding the termination process.
          nullable: true
          type: string
        agrees_to_pto_amount:
          description: Whether the employer agrees with the employee's current paid time off balance. If false, you may provide a timesheet file documenting any discrepancies.
          nullable: true
          type: boolean
        agrees_to_pto_amount_notes:
          description: Additional notes about the PTO balance, especially if there are discrepancies.
          nullable: true
          type: string
        confidential:
          description: Confidential requests are visible for who authorized the token or integration. Non-confidential requests are visible to all admins in the company.
          type: boolean
        customer_informed_employee:
          description: Whether the employer has already informed the employee about the termination. Remote advises not informing the employee until the request has been reviewed for legal risks.
          nullable: true
          type: boolean
        employee_awareness:
          description: Remote advises not to inform the employee of their termination until we review your request for legal risks. When we approve your request, you can inform the employee and we’ll take it from there. This field is only required if employee was informed before creating the offboarding request.
          properties:
            date:
              description: When the employee was told about the termination.
              format: date
              nullable: true
              type: string
            note:
              description: Notes describing how the termination was shared with the employee. Remote advises being as specific as possible, and include details about the employee’s response, if applicable.
              nullable: true
              type: string
          type: object
        personal_email:
          description: 'Remote will use this email address for post-termination communication.

            If it is not provided, this field will be derived from the employment record. Therefore, it is important to ensure that it is not a company email.

            '
          format: email
          type: string
        proposed_termination_date:
          description: In most cases, employee needs to be notified before termination. The required notice period depends on local labor laws, the employment agreement, and other factors. Remote will use those factors to determine the required notice period. Please note that we cannot commit to a termination date until we conduct a full review of the information you submit.
          format: date
          type: string
        reason_description:
          description: Description of the reason for termination
          type: string
        risk_assessment_reasons:
          description: Possible reasons for offboarding risk assessment
          items:
            enum:
            - caring_responsibilities
            - disabled_or_health_condition
            - family_leave
            - member_of_union_or_works_council
            - none_of_these
            - pregnant_or_breastfeeding
            - reported_concerns_with_workplace
            - requested_medical_or_family_leave
            - sick_leave
            type: string
          minItems: 1
          type: array
        termination_reason:
          description: 'Choose an accurate termination reason to avoid unfair or unlawful dismissal claims.


            If the termination is created before the employee''s start date, this field

            will be set to `cancellation_before_start_date`.

            '
          enum:
          - cancellation_before_start_date
          - compliance_issue
          - conversion_to_contractor
          - dissatisfaction_with_remote_service
          - end_of_fixed_term_contract_compliance_issue
          - end_of_fixed_term_contract_incapacity_to_perform_inherent_duties
          - end_of_fixed_term_contract_local_regulations_max_term_reached
          - end_of_fixed_term_contract_misconduct
          - end_of_fixed_term_contract_operational_reasons
          - end_of_fixed_term_contract_other
          - end_of_fixed_term_contract_performance
          - end_of_fixed_term_contract_redundancy
          - end_of_fixed_term_contract_values
          - gross_misconduct
          - incapacity_to_perform_inherent_duties
          - job_abandonment
          - mutual_agreement
          - other
          - performance
          - values
          - workforce_reduction
          type: string
        termination_reason_files:
          description: Any supporting documents regarding the termination reason
          items:
            $ref: '#/components/schemas/OffboardingFile'
          type: array
        timesheet_file:
          allOf:
          - $ref: '#/components/schemas/OffboardingFile'
          description: 'Paid time off accuracy


            Typically, any vacation pay accrued and unpaid at the time

            of termination must be paid out to the employee. To avoid overpaying or underpaying,

            please make sure we have an accurate account of their paid time off by querying the

            [Show Time Off Balance](#operation/get_show_timeoff_balance) endpoint,

            filtering by the `employment_id`.

            This optional document should be sent in case of any discrepancies.

            '
          type: object
        will_challenge_termination:
          description: Whether is it likely or not that the employee will challenge their termination
          type: boolean
        will_challenge_termination_description:
          description: If it is likely that the employee will challenge their termination, please provide additional details explaining the risk
          type: string
      required:
      - confidential
      - proposed_termination_date
      - termination_reason
      - risk_assessment_reasons
      - will_challenge_termination
      - reason_description
      title: TerminationDetailsParams
      type: object
    V2Offboarding:
      additionalProperties: false
      description: 'An offboarding record. Top-level fields hold the offboarding''s lifecycle state. The

        nested `request` object holds the immutable creation snapshot of the inputs submitted

        when the offboarding was created.

        '
      example:
        confidential: false
        employment_id: 1e74fdc2-7420-4eef-ab0a-b794cbbef4e1
        id: ba310525-9282-40c9-8977-14d844bf891a
        inserted_at: '2023-12-01T10:30:00Z'
        reason: performance
        request:
          additional_comments: Final paycheck to include unused PTO.
          agrees_to_pto_amount: true
          employee_awareness:
            date: '2023-11-15'
            note: Conversation held during 1:1.
          proposed_termination_date: '2024-01-15'
          reason_description: Sustained underperformance after improvement plan.
          risk_assessment_reasons:
          - none_of_these
          will_challenge_termination: false
          will_challenge_termination_description: ''
        status: pending_payment
        termination_date: '2024-01-15'
        type: termination
      properties:
        confidential:
          description: 'Whether the offboarding is confidential. Confidential offboardings are hidden from

            list and show responses by default.

            '
          nullable: true
          type: boolean
        employment_id:
          description: The unique identifier (UUID) of the employment being offboarded.
          type: string
        id:
          description: The unique identifier (UUID) of the offboarding record.
          type: string
        inserted_at:
          description: The timestamp when the offboarding record was created.
          format: datetime
          type: string
        reason:
          description: The reason for the offboarding.
          nullable: true
          type: string
        request:
          $ref: '#/components/schemas/V2OffboardingRequest'
        status:
          description: 'The current processing status of the offboarding.


            - `requested`: The offboarding request has been received and is awaiting review.

            - `in_review`: Remote is reviewing the request for legal compliance and risks.

            - `pending_payment`: The offboarding has been approved and submitted to payroll; the employee''s final payment is being processed.

            - `completed`: The offboarding is complete and the employment has been terminated.

            '
          enum:
          - requested
          - in_review
          - pending_payment
          - completed
          type: string
        termination_date:
          description: The confirmed last day of employment. May be null until Remote finalizes the date.
          format: date
          nullable: true
          type: string
        type:
          description: 'The offboarding type.

            '
          enum:
          - termination
          - resignation
          - cancellation
          - relocation
          - transfer
          - conversion
          type: string
      required:
      - id
      - status
      - type
      - employment_id
      - inserted_at
      title: V2Offboarding
      type: object
    ListOffboardingResponse:
      description: Response schema listing many offboardings
      example:
        current_page: 1
        offboardings:
        - additional_comments: ''
          agrees_to_pto_amount: true
          employer_awareness: The employer was informed on 2023-12-12
          employment_id: 1e74fdc2-7420-4eef-ab0a-b794cbbef4e1
          id: ba310525-9282-40c9-8977-14d844bf891a
          offboarding_id: 71a95754-f8f7-4763-97b4-ae20c73477a3
          proposed_last_working_day: '2023-12-20'
          requested_by: 5a31f3c1-d7a7-4311-89cb-928959d3d540
          resignation_reason: other_job_opportunity
          status: submitted
          submitted_at: '2023-04-13T13:35:06Z'
          termination_date: '2023-12-20'
          type: resignation
        total_count: 1
        total_pages: 1
      properties:
        data:
          properties:
            current_page:
              description: The current page among all of the total_pages
              type: integer
            offboardings:
              items:
                $ref: '#/components/schemas/ResignationOrTerminationOffboarding'
              type: array
            total_count:
              description: The total number of records in the result
              type: integer
            total_pages:
              description: The total number of pages the user can go through
              type: integer
          type: object
      title: ListOffboardingResponse
      type: object
    TerminationOffboarding:
      additionalProperties: false
      description: An offboarding request initiated by the employer to terminate an employment. Includes termination details, risk assessment, and status tracking through Remote's review process.
      example:
        additional_comments: additional comments regarding the termination reason
        agrees_to_pto_amount: 'true'
        confidential: false
        employee_awareness:
          date: '2023-12-12'
          note: optional text to add details
        employment_id: 1e74fdc2-7420-4eef-ab0a-b794cbbef4e1
        id: ba310525-9282-40c9-8977-14d844bf891a
        offboarding_id: 71a95754-f8f7-4763-97b4-ae20c73477a3
        proposed_termination_date: '2023-12-20'
        reason_description: They had some performance issues and mismatched expectations.
        requested_by: 5a31f3c1-d7a7-4311-89cb-928959d3d540
        risk_assessment_reasons:
        - pregnant_or_breastfeeding
        - family_leave
        status: submitted
        submitted_at: '2023-04-13T13:35:06Z'
        termination_date: '2023-12-20'
        termination_reason: workforce_reduction
        type: termination
        will_challenge_termination: true
        will_challenge_termination_description: additional details for the offboarding risk assessment
      properties:
        additional_comments:
          description: Additional comments or context about the termination provided by the employer.
          nullable: true
          type: string
        agrees_to_pto_amount:
          description: Whether the employer agreed with the employee's PTO balance at the time of the termination request.
          type: boolean
        confidential:
          description: Whether this offboarding request is confidential. Confidential requests are only visible to the user who authorized the token or integration; non-confidential requests are visible to all company admins.
          type: boolean
        employee_awareness:
          description: Details about whether and when the employee was informed about their termination. Only present if the employee was informed before the offboarding request was submitted.
          properties:
            date:
              description: The date when the employee was told about the termination.
              format: date
              nullable: true
              type: string
            note:
              description: Notes about how the termination was communicated to the employee.
              nullable: true
              type: string
          type: object
        employment_id:
          description: The unique identifier (UUID) of the employment being terminated.
          type: string
        id:
          description: The unique identifier (UUID) of the offboarding request.
          type: string
        offboarding_id:
          description: 'The unique identifier (UUID) of the offboarding record. When present, this can be used

            to query `GET /api/eor/v2/offboardings/{id}` for the v2 offboarding shape.

            '
          nullable: true
          type: string
        personal_email:
          description: 'Remote will use this email address for post-termination communication.

            If it is not provided, this field will be derived from the employment record. Therefore, it is important to ensure that it is not a company email.

            '
          format: email
          type: string
        proposed_termination_date:
          description: The employer's proposed termination date. The actual termination date may differ based on local labor laws and notice period requirements.
          format: date
          type: string
        reason_description:
          description: A detailed description of the circumstances leading to the termination.
          type: string
        requested_by:
          description: The unique identifier (UUID) of the company admin who submitted the termination request.
          type: string
        risk_assessment_reasons:
          description: Reasons that may increase the legal risk of this termination (e.g., the employee is pregnant, on family leave, etc.).
          items:
            enum:
            - caring_responsibilities
            -

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