Remote Identity Verification API

openapi: 3.0.0
info:
  title: Remote Address Details Identity Verification API
  version: 0.1.0
servers:
- url: https://gateway.remote.com/
  variables: {}
- url: https://gateway.remote-sandbox.com/
  variables: {}
security:
- OAuth2: []
tags:
- name: Identity Verification
paths:
  /v1/identity-verification/{employment_id}:
    get:
      callbacks: {}
      deprecated: false
      description: 'Gets necessary information to perform the identity verification of an employee.



        ## Scopes


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

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

        | Manage employment documents (`employment_documents`) | View identity verification (`identity_verification:read`) | Manage identity verification (`identity_verification:write`) |

        '
      operationId: get_v1_identity-verification_employment_id
      parameters:
      - description: Employment ID
        example: 0a8s2d1-employment-id-2e3f4th
        in: path
        name: employment_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdentityVerificationResponse'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - identity_verification:read
        - identity_verification:write
        - employment_documents
        - all:write
        - all:read
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - identity_verification:read
        - identity_verification:write
        - employment_documents
        - all:write
        - all:read
      summary: Get Employment Profile
      tags:
      - Identity Verification
  /v1/identity-verification/{employment_id}/decline:
    post:
      callbacks: {}
      deprecated: false
      description: 'Declines the identity verification of an employee.



        ## Scopes


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

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

        | Manage employment documents (`employment_documents`) | - | Manage identity verification (`identity_verification:write`) |

        '
      operationId: post_v1_identity-verification_employment_id_decline
      parameters:
      - description: Employment ID
        example: 0a8s2d1-employment-id-2e3f4th
        in: path
        name: employment_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - identity_verification:write
        - employment_documents
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - identity_verification:write
        - employment_documents
        - all:write
      summary: Decline Identity Verification
      tags:
      - Identity Verification
  /v1/identity-verification/{employment_id}/verify:
    post:
      callbacks: {}
      deprecated: false
      description: 'Endpoint to confirms the employment profile is from the actual employee



        ## Scopes


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

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

        | Manage employment documents (`employment_documents`) | - | Manage identity verification (`identity_verification:write`) |

        '
      operationId: post_v1_identity-verification_employment_id_verify
      parameters:
      - description: Employment ID
        example: 0a8s2d1-employment-id-2e3f4th
        in: path
        name: employment_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntityResponse'
          description: Unprocessable Entity
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - identity_verification:write
        - employment_documents
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - identity_verification:write
        - employment_documents
        - all:write
      summary: Verify Employment Identity
      tags:
      - Identity Verification
components:
  schemas:
    IdentityVerification:
      additionalProperties: false
      description: Identity Verification
      example:
        contract_id: 1c130827-f95c-4495-b7cb-5876dce686b8
        employment_document:
          id: f4e2f1fe-2056-4d9f-b9e0-ea322b781eb7
          inserted_at: '2021-01-01T00:00:00Z'
          name: 2024-05-29_Hero8r5-document.pdf
          sub_type: identity_verification
          type: mobility
        employment_image:
          id: f4e2f1fe-2056-4d9f-b9e0-ea322b781eb7
          inserted_at: '2021-01-01T00:00:00Z'
          name: 2024-05-29_Hero8r5-image.png
          sub_type: identity_verification
          type: mobility
        status: pending
      properties:
        contract_id:
          type: string
        employment_document:
          $ref: '#/components/schemas/EmploymentDocument'
        employment_image:
          $ref: '#/components/schemas/EmploymentImage'
        status:
          type: string
      required:
      - contract_id
      - status
      - employment_image
      - employment_document
      title: IdentityVerification
      type: object
    DateTimeIso8601:
      description: 'UTC date time in [ISO 8601][] format.


        [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601

        '
      example: '2021-07-15T18:18:17Z'
      format: date-time
      title: DateTimeIso8601
      type: string
    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
    IdentityVerificationResponse:
      additionalProperties: false
      description: Identity Verification response
      example:
        data:
          identity_verification_data:
            contract_id: 1c130827-f95c-4495-b7cb-5876dce686b8
            employment_document:
              id: f4e2f1fe-2056-4d9f-b9e0-ea322b781eb7
              inserted_at: '2021-01-01T00:00:00Z'
              name: 2024-05-29_Hero8r5-document.pdf
              sub_type: identity_verification
              type: mobility
            employment_image:
              id: f4e2f1fe-2056-4d9f-b9e0-ea322b781eb7
              inserted_at: '2021-01-01T00:00:00Z'
              name: 2024-05-29_Hero8r5-image.png
              sub_type: identity_verification
              type: mobility
            status: pending
      properties:
        data:
          properties:
            identity_verification_data:
              $ref: '#/components/schemas/IdentityVerification'
          type: object
      required:
      - data
      title: IdentityVerificationResponse
      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
    EmploymentImage:
      additionalProperties: false
      description: Employment image file
      example:
        id: f4e2f1fe-2056-4d9f-b9e0-ea322b781eb7
        inserted_at: '2021-01-01T00:00:00Z'
        name: 2024-05-29_Hero8r5-image.png
        sub_type: identity_verification
        type: mobility
      nullable: true
      oneOf:
      - additionalProperties: false
        description: A file associated with an employment, such as a contract, tax form, or identity document.
        example:
          id: 9880b711-file-id-ecf8f551bd78
          inserted_at: '2021-07-15T18:18:17Z'
          name: id.pdf
          sub_type: personal_id
          type: id
        properties:
          id:
            description: The unique identifier (UUID) of the file.
            type: string
          inserted_at:
            $ref: '#/components/schemas/DateTimeIso8601'
          name:
            description: The file name including extension (e.g., "id.pdf", "contract.pdf").
            type: string
          sub_type:
            description: A more specific classification of the file within its type (e.g., "personal_id" within type "id", or "ir_35" within type "contract"). Null if no sub-type applies.
            nullable: true
            type: string
          type:
            description: The broad category of the file (e.g., "id", "contract", "tax_form").
            type: string
        required:
        - id
        - inserted_at
        - name
        - type
        title: File
        type: object
      title: EmploymentImage
      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
    EmploymentDocument:
      additionalProperties: false
      description: Employment document file
      example:
        id: f4e2f1fe-2056-4d9f-b9e0-ea322b781eb7
        inserted_at: '2021-01-01T00:00:00Z'
        name: 2024-05-29_Hero8r5-document.pdf
        sub_type: identity_verification
        type: mobility
      nullable: true
      oneOf:
      - additionalProperties: false
        description: A file associated with an employment, such as a contract, tax form, or identity document.
        example:
          id: 9880b711-file-id-ecf8f551bd78
          inserted_at: '2021-07-15T18:18:17Z'
          name: id.pdf
          sub_type: personal_id
          type: id
        properties:
          id:
            description: The unique identifier (UUID) of the file.
            type: string
          inserted_at:
            $ref: '#/components/schemas/DateTimeIso8601'
          name:
            description: The file name including extension (e.g., "id.pdf", "contract.pdf").
            type: string
          sub_type:
            description: A more specific classification of the file within its type (e.g., "personal_id" within type "id", or "ir_35" within type "contract"). Null if no sub-type applies.
            nullable: true
            type: string
          type:
            description: The broad category of the file (e.g., "id", "contract", "tax_form").
            type: string
        required:
        - id
        - inserted_at
        - name
        - type
        title: File
        type: object
      title: EmploymentDocument
      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
  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