Remote Incentives API

openapi: 3.0.0
info:
  title: Remote Address Details Incentives API
  version: 0.1.0
servers:
- url: https://gateway.remote.com/
  variables: {}
- url: https://gateway.remote-sandbox.com/
  variables: {}
security:
- OAuth2: []
tags:
- name: Incentives
paths:
  /v1/employee/incentives:
    get:
      callbacks: {}
      deprecated: false
      description: 'Returns all incentives for the authenticated employee.


        ## Scopes


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

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

        | Manage expenses (`employment_payments`) | View incentives (`incentive:read`) | Manage incentives (`incentive:write`) |

        '
      operationId: get_v1_employee_incentives
      parameters: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
          description: Success
        '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
      security:
      - OAuth2Assertion:
        - https://gateway.remote.com/employment.manage
        - incentive:read
        - incentive:write
        - employment_payments
        - all:write
        - all:read
      summary: List incentives for the authenticated employee
      tags:
      - Incentives
  /v1/incentives:
    get:
      callbacks: {}
      description: 'Lists all Incentives of a company


        ## Scopes


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

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

        | Manage expenses (`employment_payments`) | View incentives (`incentive:read`) | Manage incentives (`incentive:write`) |

        '
      operationId: get_v1_incentives
      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: Filter by Employment ID
        example: 93t3j-employment-id-9suej43
        in: query
        name: employment_id
        required: false
        schema:
          type: string
      - description: Filter by Incentive status
        example: paid
        in: query
        name: status
        required: false
        schema:
          type: string
      - description: Filter by Recurring Incentive id
        example: 2f900aaf-4952-4ec4-ac7c-2b917a2b4da9
        in: query
        name: recurring_incentive_id
        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/ListIncentivesResponse'
          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
        - incentive:read
        - incentive:write
        - employment_payments
        - all:write
        - all:read
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - incentive:read
        - incentive:write
        - employment_payments
        - all:write
        - all:read
      summary: List Incentives
      tags:
      - Incentives
    post:
      callbacks: {}
      description: 'Creates an Incentive.


        Incentives use the currency of the employment specified provided in the `employment_id` field.



        ## Scopes


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

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

        | Manage expenses (`employment_payments`) | - | Manage incentives (`incentive:write`) |

        '
      operationId: post_v1_incentives
      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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOneTimeIncentiveParams'
        description: Incentive
        required: false
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncentiveResponse'
          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
        - incentive:write
        - employment_payments
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - incentive:write
        - employment_payments
        - all:write
      summary: Create Incentive
      tags:
      - Incentives
  /v1/incentives/{id}:
    delete:
      callbacks: {}
      description: 'Delete an incentive.


        `one_time` incentives that have the following status **CANNOT** be deleted:

        * `processing`

        * `paid`



        ## Scopes


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

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

        | Manage expenses (`employment_payments`) | - | Manage incentives (`incentive:write`) |

        '
      operationId: delete_v1_incentives_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: Incentive ID
        in: path
        name: id
        required: true
        schema:
          type: string
      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
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Too many requests
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - incentive:write
        - employment_payments
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - incentive:write
        - employment_payments
        - all:write
      summary: Delete an Incentive
      tags:
      - Incentives
    get:
      callbacks: {}
      description: 'Show an Incentive''s details


        ## Scopes


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

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

        | Manage expenses (`employment_payments`) | View incentives (`incentive:read`) | Manage incentives (`incentive:write`) |

        '
      operationId: get_v1_incentives_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: Incentive ID
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncentiveResponse'
          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
        - incentive:read
        - incentive:write
        - employment_payments
        - all:write
        - all:read
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - incentive:read
        - incentive:write
        - employment_payments
        - all:write
        - all:read
      summary: Show Incentive
      tags:
      - Incentives
    patch:
      callbacks: {}
      description: 'Updates an Incentive.


        Incentives use the currency of the employment specified provided in the `employment_id` field.


        The API doesn''t support updating paid incentives.



        ## Scopes


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

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

        | Manage expenses (`employment_payments`) | - | Manage incentives (`incentive:write`) |

        '
      operationId: patch_v1_incentives_id (2)
      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: Incentive ID
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateIncentiveParams'
        description: Incentive
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncentiveResponse'
          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
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Too many requests
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - incentive:write
        - employment_payments
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - incentive:write
        - employment_payments
        - all:write
      summary: Update Incentive
      tags:
      - Incentives
    put:
      callbacks: {}
      description: 'Updates an Incentive.


        Incentives use the currency of the employment specified provided in the `employment_id` field.


        The API doesn''t support updating paid incentives.



        ## Scopes


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

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

        | Manage expenses (`employment_payments`) | - | Manage incentives (`incentive:write`) |

        '
      operationId: patch_v1_incentives_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: Incentive ID
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateIncentiveParams'
        description: Incentive
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncentiveResponse'
          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
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Too many requests
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - incentive:write
        - employment_payments
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - incentive:write
        - employment_payments
        - all:write
      summary: Update Incentive
      tags:
      - Incentives
components:
  schemas:
    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
    CommonIncentiveParams:
      example:
        amount: 50000
        amount_tax_type: net
        effective_date: '2021-12-20'
        note: Bonus for moving start date to an earlier date
      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 incentive you''re offering is EUR 500.25, you would specify `50025` as

            the amount for this field.

            '
          type: integer
        amount_tax_type:
          $ref: '#/components/schemas/AmountTaxType'
        effective_date:
          description: 'The date at which the incentive should take effect.


            Note that the incentive is not paid out on the effective date, but during the

            next payroll cycle. The effective date determines which payroll cycle the

            incentive will be paid out in.


            The effective date needs to be today or a future date.


            Note for recurring incentives: since the months don''t have the same amount of days,

            if day of month of `effective_date` is one of [28, 29, 30, 31] it will be transformed to

            the last day of each month, avoiding the possibility of skipping a month in the recurrence.

            '
          format: date
          type: string
        note:
          nullable: true
          type: string
      title: CommonIncentiveParams
      type: object
    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
    ConflictResponse:
      description: Returned when the request conflicts with the current state of a resource (HTTP 409). For example, trying to create a resource that already exists or performing an action that requires the resource to be in a different state.
      example:
        message: Company needs to be in status active to manage employments
      properties:
        message:
          description: A human-readable message describing the conflict and the expected state.
          type: string
      title: ConflictResponse
      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
    CreateOneTimeIncentiveParams:
      allOf:
      - $ref: '#/components/schemas/CommonIncentiveParams'
      - properties:
          employment_id:
            type: string
          period_end:
            format: date
            nullable: true
            type: string
          period_start:
            format: date
            nullable: true
            type: string
          type:
            enum:
            - acting_up_allowance
            - allowance
            - car_allowance
            - health_and_wellness_allowance
            - internet_allowance
            - meal_allowance
            - on_call_allowance
            - parenthood_allowance
            - phone_allowance
            - relocation_allowance
            - travel_allowance
            - work_from_home_allowance
            - bonus
            - holiday_bonus
            - referral_bonus
            - retention_bonus
            - commission
            - other
            - overtime
            - stipend
            - signing_bonus
            type: string
        type: object
      example:
        amount: 50000
        amount_tax_type: net
        effective_date: '2021-12-20'
        employment_id: 5e55386e-4f4f-4def-92f4-bdc19a5ce77d
        note: Bonus for moving start date to an earlier date
        period_end: '2025-01-31'
        period_start: '2025-01-01'
        type: signing_bonus
      required:
      - type
      - amount
      - amount_tax_type
      - employment_id
      - effective_date
      title: CreateOneTimeIncentiveParams
      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
    AmountTaxType:
      description: "  Whether the amount given accounts for taxes or not.\n\n  `gross` indicates that the amount given is the amount to be paid before taxes\n  are subtracted.\n\n  `net` indicates that the amount given is the amount which will be paid to the\n  employee after taxes. Remote will gross this up to ensure the taxes are\n  included and employee receives the amount requested without further reduction.\n"
      enum:
      - gross
      - net
      example: net
      title: AmountTaxType
      type: string
    ListIncentivesResponse:
      description: Response schema listing many incentives
      example:
        current_page: 1
        incentives:
        - amount: 50000
          amount_tax_type: net
          effective_date: '2021-12-20'
          employment_id: 5e55386e-4f4f-4def-92f4-bdc19a5ce77d
          expected_payout_date: '2021-12-31'
          id: 0073fcb5-b669-4e4a-b963-2a47744e75a1
          note: Signing bonus
          recurring_incentive_id: 1c130827-f95c-4495-b7cb-5876dce686b8
          status: pending
          type: signing_bonus
        total_count: 1
        total_pages: 1
      properties:
        data:
          properties:
            current_page:
              description: The current page among all of the total_pages
              type: integer
            incentives:
              items:
                $ref: '#/components/schemas/Incentive'
              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: ListIncentivesResponse
      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
    Incentive:
      description: An incentive (bonus, commission, or other additional payment) for an employee. Incentives are paid out through payroll on the next applicable cycle after the effective date.
      example:
        amount: 50000
        amount_tax_type: net
        effective_date: '2021-12-20'
        employment_id: 5e55386e-4f4f-4def-92f4-bdc19a5ce77d
        expected_payout_date: '2021-12-31'
        id: 0073fcb5-b669-4e4a-b963-2a47744e75a1
        note: Signing bonus
        recurring_incentive_id: 1c130827-f95c-4495-b7cb-5876dce686b8
        status: pending
        type: signing_bonus
      properties:
        amount:
          description: The incentive amount in the employment's currency, in cents. For example, EUR 500.25 would be represented as 50025.
          type: integer
        amount_tax_type:
          $ref: '#/components/schemas/AmountTaxType'
        effective_date:
          description: The date the incentive takes effect. Determines which payroll cycle the incentive will be paid in.
          format: date
          nullable: true
          type: string
        employment_id:
          description: The unique identifier (UUID) of the employment this incentive belongs to.
          type: string
        expected_payout_date:
          description: The expected date when this incentive will be paid to the employee. Null if not yet determined.
          format: date
          nullable: true
          type: string
        id:
          description: The unique identifier (UUID) of the incentive.
          type: string
        note:
          description: An optional note describing the reason or context for this incentive.
          nullable: true
          type: string
        period_end:
          description: The end date of the period this incentive covers. Null for non-periodic incentives.
          format: date
          nullable: true
          type: string
        period_start:
          description: The start date of the period this incentive covers (e.g., for quarterly bonuses). Null for non-periodic incentives.
          format: date
          nullable: true
          type: string
        recurring_incentive_id:
          description: If this incentive was generated from a recurring incentive schedule, this is the ID of the parent recurring incentive. Null for one-time incentives.
          nullable: true
          type: string
        status:
          description: The current status of the incentive (e.g., "pending", "scheduled", "paid", "cancelled").
          type: string
        type:
          description: The type of incentive (e.g., "signing_bonus", "performance_bonus", "commission", "referral_bonus").
          type: string
      required:
      - id
      - employment_id
      - type
      - status
      - amount
      - amount_tax_type
      - effective_date
      title: Incentive
      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 gi

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