Remote Resignations API

openapi: 3.0.0
info:
  title: Remote Address Details Resignations API
  version: 0.1.0
servers:
- url: https://gateway.remote.com/
  variables: {}
- url: https://gateway.remote-sandbox.com/
  variables: {}
security:
- OAuth2: []
tags:
- name: Resignations
paths:
  /v1/resignations/{offboarding_request_id}/resignation-letter:
    get:
      callbacks: {}
      deprecated: false
      description: 'Downloads a resignation letter from an employment request.


        ## Scopes


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

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

        | Manage employment documents (`employment_documents`) | View resignation letters (`resignation_letter:read`) | - |

        '
      operationId: get_v1_resignations_offboarding_request_id_resignation-letter
      parameters:
      - description: Offboarding request ID
        example: 3ab2e491-ad1c-47af-849c-3d0a53e20e0d
        in: path
        name: offboarding_request_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/msword:
              schema:
                $ref: '#/components/schemas/GenericFile'
            application/pdf:
              schema:
                $ref: '#/components/schemas/GenericFile'
            application/vnd.openxmlformats-officedocument.wordprocessingml.document:
              schema:
                $ref: '#/components/schemas/GenericFile'
          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:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - resignation_letter:read
        - employment_documents
        - all:write
        - all:read
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - resignation_letter:read
        - employment_documents
        - all:write
        - all:read
      summary: Download a resignation letter
      tags:
      - Resignations
  /v1/resignations/{offboarding_request_id}:
    get:
      callbacks: {}
      deprecated: false
      description: 'Shows the details of a resignation with status `submitted`.


        ## Scopes


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

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

        | Manage employments (`employments`) | View resignations (`resignation:read`) | Manage resignations (`resignation:write`) |

        '
      operationId: get_v1_resignations_offboarding_request_id
      parameters:
      - description: Offboarding request ID
        example: 3ab2e491-ad1c-47af-849c-3d0a53e20e0d
        in: path
        name: offboarding_request_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResignationResponse'
          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: Unprocessable Entity
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - resignation:read
        - resignation:write
        - employments
        - all:write
        - all:read
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - resignation:read
        - resignation:write
        - employments
        - all:write
        - all:read
      summary: Show Resignation
      tags:
      - Resignations
  /v1/resignations/{offboarding_request_id}/validate:
    put:
      callbacks: {}
      deprecated: false
      description: 'Validates a resignation employment request


        ## Scopes


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

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

        | Manage employments (`employments`) | - | Manage resignations (`resignation:write`) |

        '
      operationId: put_v1_resignations_offboarding_request_id_validate
      parameters:
      - description: Offboarding request ID
        example: 3ab2e491-ad1c-47af-849c-3d0a53e20e0d
        in: path
        name: offboarding_request_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateResignationRequestParams'
        description: ValidateResignation
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
          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: Unprocessable Entity
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - resignation:write
        - employments
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - resignation:write
        - employments
        - all:write
      summary: Validate resignation request
      tags:
      - Resignations
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
    ResignationResponse:
      description: Resignation response
      example:
        data:
          resignation:
            contract_currency_code: USD
            contract_job_title: Developer
            contract_proabtion_period_passed: true
            contract_probation_period_end_date: '2021-06-15'
            contract_start_date: '2021-03-15'
            days_of_notice: 31
            paid_timeoffs_breakdown_labels:
            - 'Used until today: 60 days'
            - 'Waiting for approval: 0 days'
            proposed_last_day: '2024-04-12'
            resignation_date: '2024-03-12'
            resignation_reason_label: Retirement
      properties:
        data:
          $ref: '#/components/schemas/Resignation'
      title: ResignationResponse
      type: object
    UnauthorizedResponse:
      description: Returned when the request does not include valid authentication credentials. Ensure you are passing a valid OAuth2 access token or API token in the Authorization header.
      example:
        message: Unauthorized
      properties:
        message:
          pattern: Unauthorized
          type: string
      required:
      - message
      title: UnauthorizedResponse
      type: object
    ValidateResignationRequestParams:
      example:
        accepts_proposed_notice: false
        agrees_to_pto_amount: false
        agrees_to_pto_amount_notes: I don't agree.
        agrees_to_resignation_reason: false
        agrees_to_resignation_reason_notes: I don't agree.
        has_additional_information: true
        has_additional_information_notes: Some extra info.
        has_more_salary_info: true
        has_more_salary_info_notes: Some info about the salary.
        is_owed_outstanding_reimbursements: true
        owed_outstanding_reimbursements:
          amount: 1500
          notes: Compensation.
        proposed_last_date:
          date: '2042-04-15'
          notes: This date is better.
        will_take_more_pto: true
        will_take_more_pto_notes: 3 more days.
      oneOf:
      - $ref: '#/components/schemas/ResignationAfterStartDateRequestParams'
      - $ref: '#/components/schemas/ResignationBeforeStartDateRequestParams'
      title: ValidateResignationRequestParams
      type: object
    ForbiddenResponse:
      description: Returned when the authenticated user or token does not have permission to perform the requested action. Check that the token has the required OAuth2 scopes and that the user has the necessary role.
      example:
        message: Forbidden
      properties:
        message:
          pattern: Forbidden
          type: string
      required:
      - message
      title: ForbiddenResponse
      type: object
    UnprocessableEntityResponse:
      anyOf:
      - properties:
          errors:
            type: object
        required:
        - errors
        type: object
      - properties:
          message:
            oneOf:
            - type: string
            - $ref: '#/components/schemas/ParameterError'
            - items:
                $ref: '#/components/schemas/ParameterError'
              title: ParameterErrors
              type: array
            - $ref: '#/components/schemas/ActionError'
            - items:
                $ref: '#/components/schemas/ActionError'
              title: ActionErrors
              type: array
        required:
        - message
        type: object
      example:
        errors:
          some_field:
          - is invalid
      title: UnprocessableEntityResponse
      type: object
    NotFoundResponse:
      description: Returned when the requested resource does not exist or is not accessible with the current authentication credentials.
      example:
        message: '{resource} not found'
      properties:
        message:
          description: A message indicating which resource was not found.
          pattern: Not Found
          type: string
      title: NotFoundResponse
      type: object
    ResignationBeforeStartDateRequestParams:
      additionalProperties: false
      example:
        proposed_resignation_accepted: false
        proposed_resignation_accepted_notes: I do not accept
      properties:
        proposed_resignation_accepted:
          description: Whether the employer accepts the employee's resignation. If false, notes are required explaining why.
          type: boolean
        proposed_resignation_accepted_notes:
          description: Required if `proposed_resignation_accepted` is set to false.
          type: string
      required:
      - proposed_resignation_accepted
      title: ResignationBeforeStartDateRequestParams
      type: object
    BadRequestResponse:
      description: Returned when the request is malformed or contains invalid parameters. The message may be a simple string or a structured object with a code and detailed message.
      example:
        message: invalid {resource}
      oneOf:
      - properties:
          message:
            description: A human-readable error message describing what was wrong with the request.
            type: string
        required:
        - message
        type: object
      - properties:
          message:
            properties:
              code:
                type: string
              message:
                type: string
            required:
            - code
            - message
            type: object
        type: object
      title: BadRequestResponse
      type: object
    GenericFile:
      description: A file represented as a base64-encoded string.
      example: base64 encoded content
      format: binary
      title: GenericFile
      type: string
    Resignation:
      description: Resignation details for an offboarding request. The shape depends on whether the employee resigned before or after their employment start date.
      example:
        resignation:
          contract_currency_code: USD
          contract_job_title: Developer
          contract_proabtion_period_passed: true
          contract_probation_period_end_date: '2021-06-15'
          contract_start_date: '2021-03-15'
          days_of_notice: 31
          paid_timeoffs_breakdown_labels:
          - 'Used until today: 60 days'
          - 'Waiting for approval: 0 days'
          proposed_last_day: '2024-04-12'
          resignation_date: '2024-03-12'
          resignation_reason_label: Retirement
      properties:
        resignation:
          anyOf:
          - $ref: '#/components/schemas/ResignationBeforeStartDate'
          - $ref: '#/components/schemas/ResignationAfterStartDate'
          type: object
      title: Resignation
      type: object
    ResignationAfterStartDateRequestParams:
      additionalProperties: false
      example:
        accepts_proposed_notice: false
        agrees_to_pto_amount: false
        agrees_to_pto_amount_notes: I don't agree.
        agrees_to_resignation_reason: false
        agrees_to_resignation_reason_notes: I don't agree.
        has_additional_information: true
        has_additional_information_notes: Some extra info.
        has_more_salary_info: true
        has_more_salary_info_notes: Some info about the salary.
        is_owed_outstanding_reimbursements: true
        owed_outstanding_reimbursements:
          amount: 1500
          notes: Compensation.
        proposed_last_date:
          date: '2042-04-15'
          notes: This date is better.
        will_take_more_pto: true
        will_take_more_pto_notes: 3 more days.
      properties:
        accepts_proposed_notice:
          description: Whether the employer accepts the proposed notice period and last working day. If false, provide an alternative `proposed_last_date`.
          type: boolean
        agrees_to_pto_amount:
          description: Whether the employer agrees with the employee's current PTO balance. If false, provide notes explaining the discrepancy.
          type: boolean
        agrees_to_pto_amount_notes:
          description: Required if `agrees_to_pto_amount` is set to false.
          type: string
        agrees_to_resignation_reason:
          description: Whether the employer agrees with the resignation reason stated by the employee. If false, provide notes with the employer's perspective.
          type: boolean
        agrees_to_resignation_reason_notes:
          description: required if `agrees_to_resignation_reason` is set to false.
          type: string
        has_additional_information:
          description: Whether the employer has additional information to share about the resignation. If true, provide notes.
          type: boolean
        has_additional_information_notes:
          description: required if `has_additional_information` is set to true.
          type: string
        has_more_salary_info:
          description: Whether there are salary adjustments or additional salary information to communicate. If true, provide notes.
          type: boolean
        has_more_salary_info_notes:
          description: required if `has_more_salary_info` is set to true.
          type: string
        is_owed_outstanding_reimbursements:
          description: Whether the employee is owed any outstanding expense reimbursements. If true, provide the amount and notes.
          type: boolean
        owed_outstanding_reimbursements:
          description: required if `is_owed_outstanding_reimbursements` is set to true.
          properties:
            amount:
              description: 'The amount (in the currency of the employment) to be given to the employee.


                This field accepts fractional amounts as well. However to avoid precision issues

                and errors that can arise from storing fractional amounts, the Remote API only

                accepts currencies and their fractional amounts as integers. This means you

                should append fractional amounts to the end of the amount you''re passing in with

                this field.


                For example, if the amount you''re offering is EUR 500.25, you would specify `50025` as

                the amount for this field.

                '
              type: integer
            notes:
              type: string
          type: object
        proposed_last_date:
          description: Required if `accepts_proposed_notice` is set to false.
          properties:
            date:
              format: date
              type: string
            notes:
              type: string
          type: object
        timesheet_file:
          allOf:
          - $ref: '#/components/schemas/ResignationFile'
          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_take_more_pto:
          description: Whether the employee intends to take more PTO before their last working day. If true, provide notes with details.
          type: boolean
        will_take_more_pto_notes:
          description: required if `will_take_more_pto` is set to true.
          type: string
      required:
      - accepts_proposed_notice
      - agrees_to_pto_amount
      - agrees_to_resignation_reason
      - has_additional_information
      - has_more_salary_info
      - is_owed_outstanding_reimbursements
      - will_take_more_pto
      title: ResignationAfterStartDateRequestParams
      type: object
    ResignationFile:
      additionalProperties: false
      example:
        content: base64 encoded content
        name: id.pdf
      properties:
        content:
          description: The content in base64 encoding
          format: binary
          type: string
        name:
          description: The file name
          type: string
      required:
      - name
      - content
      title: ResignationFile
      type: object
    TooManyRequestsResponse:
      description: Returned when the API rate limit has been exceeded (HTTP 429). Wait before retrying. Check the `Retry-After` response header for the recommended wait time.
      example:
        message: Too many requests
      properties:
        message:
          pattern: Too many requests
          type: string
      title: TooManyRequestsResponse
      type: object
    ResignationAfterStartDate:
      description: Resignation details for an employee who resigned after their employment start date. Includes contract terms, notice period calculations, and PTO breakdown needed for the employer to validate the resignation.
      example:
        contract_currency_code: USD
        contract_job_title: Developer
        contract_proabtion_period_passed: true
        contract_probation_period_end_date: '2021-06-15'
        contract_start_date: '2021-03-15'
        days_of_notice: 31
        paid_timeoffs_breakdown_labels:
        - 'Used until today: 60 days'
        - 'Waiting for approval: 0 days'
        proposed_last_day: '2024-04-12'
        resignation_date: '2024-03-12'
        resignation_reason_label: Retirement
      properties:
        contract_currency_code:
          description: The ISO 4217 currency code of the employee's contract (used for any reimbursement calculations).
          type: string
        contract_job_title:
          description: The job title from the employee's contract.
          type: string
        contract_proabtion_period_passed:
          description: Whether the employee's probation period has passed. Affects notice period requirements in many jurisdictions.
          type: boolean
        contract_probation_period_end_date:
          description: The end date of the employee's probation period. Null if the contract has no probation period.
          format: date
          nullable: true
          type: string
        contract_start_date:
          description: The original start date from the employee's contract.
          format: date
          type: string
        days_of_notice:
          description: The number of calendar days of notice required based on the contract terms and local labor laws.
          type: integer
        paid_timeoffs_breakdown_labels:
          description: 'Human-readable breakdown of the employee''s paid time off usage and balance (e.g., "Used until today: 60 days", "Waiting for approval: 0 days").'
          items:
            type: string
          type: array
        proposed_last_day:
          description: The employee's proposed last working day, calculated based on the notice period and local labor laws.
          format: date
          type: string
        resignation_date:
          description: The date the employee submitted their resignation (UTC).
          format: date
          type: string
        resignation_reason_label:
          description: A human-readable label describing the reason for resignation (e.g., "Retirement", "Other job opportunity").
          type: string
      required:
      - contract_job_title
      - contract_start_date
      - resignation_date
      - resignation_reason_label
      - contract_probation_period_end_date
      - contract_proabtion_period_passed
      - contract_currency_code
      - proposed_last_day
      - days_of_notice
      - paid_timeoffs_breakdown_labels
      title: ResignationAfterStartDate
      type: object
    SuccessResponse:
      description: A generic success response returned by operations that don't produce a specific resource (e.g., updates, deletes).
      example:
        data:
          status: ok
      properties:
        data:
          properties:
            status:
              description: The result status. Always `"ok"` for successful operations.
              type: string
          type: object
      required:
      - data
      title: SuccessResponse
      type: object
    ActionError:
      properties:
        action:
          description: The action that lead to the error message.
          type: string
        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
      required:
      - code
      - message
      - action
      title: ActionError
      type: object
    ResignationBeforeStartDate:
      description: Resignation details for an employee who resigned before their employment start date. Contains basic contract and resignation information only.
      example:
        contract_job_title: Developer
        contract_start_date: '2024-04-12'
        resignation_date: '2024-04-03'
        resignation_reason_label: Decided not to join before starting
      properties:
        contract_job_title:
          description: The job title from the employee's contract.
          type: string
        contract_start_date:
          description: The original start date from the employee's contract.
          format: date
          type: string
        resignation_date:
          description: The date the employee submitted their resignation (UTC).
          format: date
          type: string
        resignation_reason_label:
          description: A human-readable label describing the reason for resignation (e.g., "Decided not to join before starting").
          type: string
      required:
      - contract_job_title
      - contract_start_date
      - resignation_date
      - resignation_reason_label
      title: ResignationBeforeStartDate
      type: object
  securitySchemes:
    BasicAuth:
      description: 'Authenticate using the basic authentication for partners.


        Use the CLIENT_ID as login and CLIENT_SECRET as password.

        '
      scheme: basic
      type: http
    ClientToken:
      description: 'Authenticate a partner using only the the provided `client_token`.


        This authentication method only allows accessing marketing endpoints.

        '
      scheme: bearer
      type: http
    CustomerAPIToken:
      description: 'Authenticate using API Key generated by the customer in their Integration Settings page.

        '
      scheme: bearer
      type: http
    OAuth2:
      description: 'Authenticate using OAuth 2.0 protocol.

        '
      flows:
        authorizationCode:
          authorizationUrl: /auth/oauth2/authorize
          scopes:
            company_department:read: company_department:read
            webhook:write: webhook:write
            magic_link:write: magic_link:write
            offboarding:write: offboarding:write
            custom_field:write: custom_field:write
            address:write: address:write
            expense:read: expense:read
            employment:write: employment:write
            identity_verification:write: identity_verification:write
            timesheet:write: timesheet:write
            travel_letter:write: travel_letter:write
            incentive:read: incentive:read
            personal_detail:read: personal_detail:read
            invoices:write: invoices:write
            work_authorization:write: work_authorization:write
            timeoff:write: timeoff:write
            company_structure:read: company_structure:read
            benefit_renewal:write: benefit_renewal:write
            benefit_offer:read: benefit_offer:read
            employment_documents: employment_documents
            onboarding:write: onboarding:write
            payroll_run:read: payroll_run:read
            risk_reserve:write: risk_reserve:write
            invoices: invoices
            resignation_letter:read: resignation_letter:read
            resignation:read: resignation:read
            convert_currency:read: convert_currency:read
            employments: employments
            probation_document:read: probation_document:read
            company_admin: company_admin
            payroll: payroll
            help_center_article:read: help_center_article:read
            timesheet:read: timesheet:read
            custom_field_value:write: custom_field_value:write
            company_currencies:read: company_currencies:read
            payslip:read: payslip:read
            pay_item:write: pay_item:write
            resignation:write: resignation:write
            custom_field:read: custom_field:read
            payroll_calendar:read: payroll_calendar:read
            contract_amendment:write: contract_amendment:write
            offboarding:read: offboarding:read
            timeoff:read: timeoff:read
            probation_document:write: probation_document:write
            country:read: country:read
            webhook:read: webhook:read
            company_department:write: company_department:write
            company_manager:read: company_manager:read
            pay_item:read: pay_item:read
            contract_amendment:read: contract_amendment:read
            company:read: company:read
            sso_configuration:write: sso_configuration:write
            benefit_offer:write: benefit_offer:write
            contract_eligibility:write: contract_eligibility:write
            benefit_renewal:read: benefit_renewal:read
            background_check:read: background_check:read
            custom_field_value:read: custom_field_value:read
            expense:write: expense:write
            identity_verification:read: identity_verification:read
            address:read: address:read
            document:write: document:write
            time_and_attendance: time_and_attendance
            employment_payments: employment_payments
            form:read: form:read
            work_authorization:read: work_authorization:read
            invoices:read: invoices:read
            incentive:write: incentive:write
            employment:read: employment:read
            contract:read: contract:read
            company_manager:write: company_manager:write
            travel_letter:read: travel_letter:read
            document:read: document:read
            sso_configuration:read: sso_configuration:read
          tokenUrl: /auth/oauth2/token
        clientCredentials:
          scopes:
            company:read: company:read
            company:write: company:write
            company_admin: company_admin
            company_management: company_management
            convert_currency:read: convert_currency:read
            country:read: country:read
            employment_documents: employment_documents
            employment_payments: employment_payments
            employments: employments
            help_center_article:read: help_center_article:read
            invoices: invoices
            payroll: payroll
            payroll_calendar:read: payroll_calendar:read
            pricing_plan:read: pricing_plan:read
            pricing_plan:write: pricing_plan:write
            time_and_attendance: time_and_attendance
            webhook:read: webhook:read
            webhook:write: webhook:write
          tokenUrl: /auth/oauth2/token
      type: oauth2
    OAuth2Assertion:
      description: 'Authenticate as the employee using the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant in the OAuth2 protocol.

        '
      flows:
        clientCredentials:
          scopes:
            address:read: address:read
            address:write: address:write
            bank_account:read: bank_account:read
            bank_account:write: bank_account:write
            document:read: document:read
            document:write: document:write
            emergency_contact:read: emergency_contact:read
            emergency_contact:write: emergency_contact:write
            employment_documents: employment_documents
            employment_payments: employment_payments
            employments: employments
            expense:read: expense:read
        

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