Remote Time Off Balances API

openapi: 3.0.0
info:
  title: Remote Address Details Time Off Balances API
  version: 0.1.0
servers:
- url: https://gateway.remote.com/
  variables: {}
- url: https://gateway.remote-sandbox.com/
  variables: {}
security:
- OAuth2: []
tags:
- name: Time Off Balances
paths:
  /v1/timeoff-balances/{employment_id}:
    get:
      callbacks: {}
      deprecated: true
      description: 'Shows the time off balance for the given employment_id.


        Deprecated since February 2025 in favour of **[List Leave Policies Summary](#tag/Leave-Policies/operation/get_index_leave_policies_summary)** endpoint.



        ## Scopes


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

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

        | Manage timeoffs (`time_and_attendance`) | View timeoffs (`timeoff:read`) | Manage timeoffs (`timeoff:write`) |

        '
      operationId: get_v1_timeoff-balances_employment_id
      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: Employment ID for which to show the time off balance
        example: 03675381-50c9-492d-b8ed-e84e99046091
        in: path
        name: employment_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeoffBalanceResponse'
          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/TimeoffBalanceNotFoundResponse'
          description: TimeoffBalanceNotFoundResponse
        '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
        - timeoff:read
        - timeoff:write
        - time_and_attendance
        - all:write
        - all:read
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - timeoff:read
        - timeoff:write
        - time_and_attendance
        - all:write
        - all:read
      summary: Show Time Off Balance
      tags:
      - Time Off Balances
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
    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
    ResourceErrorResponse:
      description: Returned when an operation fails due to a resource-level conflict or constraint. Includes a structured error with a machine-readable code, a human-readable message, and the type and ID of the affected resource.
      example:
        message:
          code: resource_already_exists
          message: There is already a submitted Employee termination request for this user, so you can't submit another one
          resource_id: aca8ba1f-8d3a-4de8-9ab4-e0fcb4b210be
          resource_type: termination_request
      properties:
        message:
          properties:
            code:
              description: A machine-readable error code identifying the specific type of resource error.
              enum:
              - resource_not_eligible
              - resource_already_exists
              - action_unrecognized
              - action_invalid
              - parameter_invalid_date
              - resource_invalid_state
              - parameter_value_invalid
              - parameter_value_unknown
              - request_body_empty
              - request_internal_server_error
              - parameter_required_missing
              - parameter_one_of_required_missing
              - parameter_too_many
              - parameter_unknown
              - parameter_map_empty
              - resource_not_supported_for_country
              type: string
            message:
              description: A human-readable message explaining the error and how to resolve it.
              type: string
            resource_id:
              description: The unique identifier of the specific resource that caused the error. May be null if the resource has not been created yet.
              nullable: true
              type: string
            resource_type:
              description: The type of resource that caused the error (e.g., "termination_request", "employment").
              type: string
          type: object
      required:
      - message
      title: ResourceErrorResponse
      type: object
    TimeoffBalance:
      example:
        contractual_entitled:
          days: 25
          hours: 0
        leave_entitlements:
        - entitled:
            days: 28
            hours: 0
          expiry_date: '2022-12-31'
          name: Annual paid time off
          remaining:
            days: 25
            hours: 0
          taken:
            days: 3
            hours: 0
          type: annual_paid_timeoff
        - entitled:
            days: 3
            hours: 0
          expiry_date: '2022-12-31'
          name: Extra days for good performance
          remaining:
            days: 3
            hours: 0
          taken:
            days: 0
            hours: 0
          type: additional_pto
        taken:
          days: 3
          hours: 0
        total_entitled_days: 31
        working_hours_per_day: 8
      properties:
        contractual_entitled:
          description: 'Number of time off days for the employment, based on their contract.


            The value of this field is `0` if the employment''s contract does not

            include that information.

            '
          type: integer
        contractual_leave_entitlement_type:
          description: 'Leave entitlement type for the employment, based on their contract.


            The value of this field is `fixed` when the employment has a fixed

            limit of time off days to be taken, and `unlimited` otherwise.

            '
          type: string
        taken:
          description: 'Number of time off days taken by the employment as of today.


            You can get a list of taken time off data for this employment using the

            [list time off endpoint](#tag/Time-Off/operation/get_index_timeoff).

            '
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/TimeoffDaysAndHours'
          type: object
        timeoff_entitlements:
          description: 'A list of individual time off entitlements for the employment. This list

            gives more granular details for the type of time off that''s available

            to the employment.

            '
          items:
            $ref: '#/components/schemas/TimeoffEntitlement'
          type: array
        total_entitled_days:
          description: 'Number of time off days for the employment, based on their contract and

            any additional time off that''s granted to them.


            This is the sum of all `entitled` fields in the `leave_entitlements`

            array, but does not take the hours into account.

            '
          type: integer
        upcoming_approved:
          description: 'Number of future, approved time off days for the employment, as of today.


            You can get a list of approved time off data for this employment using the

            [list time off endpoint](#tag/Time-Off/operation/get_index_timeoff).

            '
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/TimeoffDaysAndHours'
          type: object
        upcoming_requested:
          description: 'Number of future, requested time off days for the employment, as of today.


            You can get a list of requested time off data for this employment using the

            [list time off endpoint](#tag/Time-Off/operation/get_index_timeoff).

            '
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/TimeoffDaysAndHours'
          type: object
        working_hours_per_day:
          description: The number of working hours per day as defined in the employment's contract. Used to convert between days and hours.
          type: integer
      required:
      - timeoff_entitlements
      - taken
      - upcoming_approved
      - upcoming_requested
      - working_hours_per_day
      - contractual_leave_entitlement_type
      title: TimeoffBalance
      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
    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
    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
    TimeoffBalanceNotSupportedResponse:
      example:
        message:
          code: resource_already_exists
          message: There is already a submitted Employee termination request for this user, so you can't submit another one
          resource_id: aca8ba1f-8d3a-4de8-9ab4-e0fcb4b210be
          resource_type: termination_request
      oneOf:
      - $ref: '#/components/schemas/ResourceErrorResponse'
      title: TimeoffBalanceNotSupportedResponse
      type: object
    TimeoffBalanceNotFoundResponse:
      example:
        message: '{resource} not found'
      oneOf:
      - $ref: '#/components/schemas/TimeoffBalanceNotSupportedResponse'
      - $ref: '#/components/schemas/NotFoundResponse'
      title: TimeoffBalanceNotFoundResponse
      type: object
    TimeoffDaysAndHours:
      example:
        days: 1
        hours: 3
      properties:
        days:
          description: The number of whole days.
          type: integer
        hours:
          description: The number of additional hours beyond whole days.
          type: integer
      title: TimeoffDaysAndHours
      type: object
    TimeoffBalanceResponse:
      description: Time Off Balance response
      example:
        data:
          timeoff_balance:
            contractual_entitled:
              days: 25
              hours: 0
            leave_entitlements:
            - entitled:
                days: 28
                hours: 0
              expiry_date: '2022-12-31'
              name: Annual paid time off
              remaining:
                days: 25
                hours: 0
              taken:
                days: 3
                hours: 0
              type: annual_paid_timeoff
            - entitled:
                days: 3
                hours: 0
              expiry_date: '2022-12-31'
              name: Extra days for good performance
              remaining:
                days: 3
                hours: 0
              taken:
                days: 0
                hours: 0
              type: additional_pto
            taken:
              days: 3
              hours: 0
            total_entitled_days: 31
            working_hours_per_day: 8
      properties:
        data:
          properties:
            timeoff_balance:
              $ref: '#/components/schemas/TimeoffBalance'
          required:
          - timeoff_balance
          type: object
      required:
      - data
      title: TimeoffBalanceResponse
      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
    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
    TimeoffEntitlement:
      description: 'Detailed breakdown of an employment''s time off balance.

        '
      example:
        available:
          days: 15
          hours: 4
        expiry_date: '2022-12-31'
        name: Extra days for good performance
        taken:
          days: 15
          hours: 4
        type: additional_pto
      properties:
        can_expire:
          description: 'Indicates whether this entitlement can expire.


            When `false`, `expiry_date` will be `nil`.

            '
          type: boolean
        entitled:
          description: 'Indicates how much this time off this entitlement contributes to the total time

            off entitlement.

            '
          oneOf:
          - $ref: '#/components/schemas/TimeoffDaysAndHours'
          type: object
        expiry_date:
          description: 'Indicates the date this entitlement expires and is no longer counted

            towards the total time off entitlement for the employment.


            When this entitlement doesn''t expire, `expiry_date` will be set to

            `nil`. Use the `can_expire` parameter to determine whether

            an entitlement can expire or not.

            '
          format: date
          nullable: true
          type: string
        name:
          description: A human-readable name for this entitlement (e.g., "Annual paid time off", "Extra days for good performance"). Null for the default contractual entitlement.
          nullable: true
          type: string
        remaining:
          description: 'Indicates how much time off the employment has remaining in this entitlement.

            '
          oneOf:
          - $ref: '#/components/schemas/TimeoffDaysAndHours'
          type: object
        taken:
          description: 'Indicates how much time off the employment has taken from this entitlement.

            '
          oneOf:
          - $ref: '#/components/schemas/TimeoffDaysAndHours'
          type: object
        type:
          description: 'Indicates the type of the time off entitlement.


            `annual_paid_timeoff` entitlements are calculated from the employment''s

            contract. All other time off entitlements are granted by the employer

            or automatically by the country of employment.

            '
          enum:
          - carryover_pto
          - additional_pto
          - transfer_pto
          - annual_paid_timeoff
          type: string
      required:
      - name
      - expiry_date
      - can_expire
      - entitled
      - taken
      - remaining
      - type
      title: TimeoffEntitlement
      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
            incentive:read: incentive:read
            payroll: payroll
            payslip:read: payslip:read
            personal_detail:read: personal_detail:read
            personal_detail:write: personal_detail:write
            time_and_attendance: time_and_attendance
            timeoff:read: timeoff:read
            timeoff:write: timeoff:write
            timesheet:read: timesheet:read
          tokenUrl: /auth/oauth2/token
          x-assertionType: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
      type: oauth2
    OAuth2AuthorizationCode:
      description: 'Authenticate as the token authorizer using `authorization_code` / `refresh_token` grants in the OAuth 2.0 protocol.

        '
      flows:
        authorizationCode:
          authorizationUrl: /auth/oauth2/authorize
          refreshUrl: /auth/oauth2/token
          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
      type: oauth2
    OAuth2ClientCredentials:
      description: 'Authenticate using `client_credentials` grant in the OAuth 2.0 protocol.

        '
      flows:
        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