Remote Contract Documents API

openapi: 3.0.0
info:
  title: Remote Address Details Contract Documents API
  version: 0.1.0
servers:
- url: https://gateway.remote.com/
  variables: {}
- url: https://gateway.remote-sandbox.com/
  variables: {}
security:
- OAuth2: []
tags:
- name: Contract Documents
paths:
  /v1/contractors/employments/{employment_id}/contract-documents/{id}:
    get:
      callbacks: {}
      deprecated: false
      description: '## Scopes


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

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

        | Manage employment documents (`employment_documents`) | View documents (`document:read`) | Manage documents (`document:write`) |

        '
      operationId: get_v1_contractors_employments_employment_id_contract-documents_id
      parameters:
      - description: Employment ID
        example: 93t3j-file-id-9suej43
        in: path
        name: employment_id
        required: true
        schema:
          type: string
      - description: Document ID
        example: 93t3j-file-id-9suej43
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractDocumentResponse'
          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
        - document:read
        - document:write
        - employment_documents
        - all:write
        - all:read
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - document:read
        - document:write
        - employment_documents
        - all:write
        - all:read
      summary: Return a base64 encoded version of the contract document
      tags:
      - Contract Documents
  /v1/contractors/employments/{employment_id}/contract-documents:
    post:
      callbacks: {}
      deprecated: false
      description: 'Create a contract document for a contractor.



        ## Scopes


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

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

        | Manage employment documents (`employment_documents`) | - | Manage documents (`document:write`) |

        '
      operationId: post_v1_contractors_employments_employment_id_contract-documents
      parameters:
      - description: Employment ID
        example: 1a716003-ae89-4810-aa00-25df6e799162
        in: path
        name: employment_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContractDocument'
        description: CreateContractDocumentParams
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateContractDocumentResponse'
          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
        - document:write
        - employment_documents
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - document:write
        - employment_documents
        - all:write
      summary: Create a contract document for a contractor
      tags:
      - Contract Documents
  /v1/contractors/employments/{employment_id}/contract-documents/{contract_document_id}/sign:
    post:
      callbacks: {}
      deprecated: false
      description: '## Scopes


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

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

        | Manage employment documents (`employment_documents`) | - | Manage documents (`document:write`) |

        '
      operationId: post_v1_contractors_employments_employment_id_contract-documents_contract_document_id_sign
      parameters:
      - description: Employment ID
        example: 93t3j-file-id-9suej43
        in: path
        name: employment_id
        required: true
        schema:
          type: string
      - description: Document ID
        example: 93t3j-file-id-9suej43
        in: path
        name: contract_document_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignContractDocument'
        description: SignContractDocument
        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
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Forbidden
      security:
      - CustomerAPIToken:
        - https://gateway.remote.com/company.manage
        - document:write
        - employment_documents
        - all:write
        OAuth2AuthorizationCode:
        - https://gateway.remote.com/company.manage
        - document:write
        - employment_documents
        - all:write
      summary: Sign a document for a contractor
      tags:
      - Contract Documents
components:
  schemas:
    SignatoryType:
      description: The role of this signatory in the contract signing process
      enum:
      - company
      - employee
      - admin
      - external
      - unknown
      example: company
      title: SignatoryType
      type: string
    CreateContractDocumentResponse:
      description: Contract document response
      example:
        data:
          contract_document:
            id: 0073fcb5-b669-4e4a-b963-2a47744e75a1
            status: draft
      properties:
        data:
          properties:
            contract_document:
              $ref: '#/components/schemas/ContractDocument'
          required:
          - contract_document
          type: object
      required:
      - data
      title: CreateContractDocumentResponse
      type: object
    SignContractDocument:
      description: SignContractDocument schema
      example:
        signature: Don Van Vliet
      properties:
        signature:
          description: The signer's full legal name as their electronic signature.
          type: string
      required:
      - signature
      title: SignContractDocument
      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
    SignatoryStatus:
      description: Current signing status of this signatory
      enum:
      - pending
      - signed
      - unassigned
      example: pending
      title: SignatoryStatus
      type: string
    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
    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
    Signatory:
      additionalProperties: false
      description: A signatory on a contract document. For company and employee signatories, `user_id` is provided. For other signatory types, `user_id` is null.
      example:
        email: john@example.com
        name: John Doe
        signature: data:image/png;base64,iVBORw0KGgo...
        signed_at: '2024-01-15T10:30:00Z'
        status: signed
        type: employee
        user_id: 0073fcb5-b669-4e4a-b963-2a47744e75a1
      properties:
        email:
          description: Email address of the signatory
          nullable: true
          type: string
        name:
          description: Full name of the signatory
          nullable: true
          type: string
        signature:
          description: Signature image as a data URI (e.g. `data:image/png;base64,...`), null if not yet signed
          nullable: true
          type: string
        signature_method:
          description: Signing method used by this signatory
          enum:
          - in_platform
          - docusign
          type: string
        signature_type:
          description: Legal signature level applied when signing
          enum:
          - standard
          - qes
          - aes
          - ses
          type: string
        signed_at:
          description: Timestamp when the signatory signed the document, null if not yet signed
          format: date-time
          nullable: true
          type: string
        status:
          $ref: '#/components/schemas/SignatoryStatus'
        type:
          $ref: '#/components/schemas/SignatoryType'
        user_id:
          description: User identifier for internal signatories, null for external signatories
          nullable: true
          type: string
      required:
      - type
      - status
      title: Signatory
      type: object
    CreateContractDocument:
      description: Parameters for creating a contract document
      example:
        contract_document: {}
        skip_ai_checks: false
      properties:
        contract_document:
          description: '  Contract document parameters. Its properties may vary depending on the country.

            '
          type: object
        skip_ai_checks:
          description: When true, skips AI-based compliance checks (e.g. services and deliverables classification). Defaults to false.
          type: boolean
      required:
      - contract_document
      title: CreateContractDocument
      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
    ContractDocument:
      additionalProperties: false
      description: A contract document for a contractor employment, tracking its signing status.
      example:
        id: 0073fcb5-b669-4e4a-b963-2a47744e75a1
        status: draft
      properties:
        id:
          description: The unique identifier (UUID) of the contract document.
          type: string
        status:
          $ref: '#/components/schemas/ContractorContractDocumentStatus'
      required:
      - id
      - status
      title: ContractDocument
      type: object
    ContractDocumentResponse:
      additionalProperties: false
      description: Return a base64 encoded contract document
      example:
        data:
          contract_document:
            content: data:application/pdf;base64,iVBORw0KGgoAAAANSUhEUgAAAJUAAACVCAYAAABRorhPAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWF...
            name: id.pdf
            signatories:
            - email: john@example.com
              name: John Doe
              signature: data:image/png;base64,iVBORw0KGgo...
              signed_at: '2024-01-15T10:30:00Z'
              status: signed
              type: employee
              user_id: 0073fcb5-b669-4e4a-b963-2a47744e75a1
            status: finished
      properties:
        data:
          properties:
            contract_document:
              properties:
                content:
                  format: binary
                  type: string
                name:
                  type: string
                signatories:
                  items:
                    $ref: '#/components/schemas/Signatory'
                  type: array
                status:
                  $ref: '#/components/schemas/ContractorContractDocumentStatus'
              required:
              - content
              - name
              - signatories
              - status
              type: object
          required:
          - contract_document
          type: object
      required:
      - data
      title: ContractDocumentResponse
      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
    ContractorContractDocumentStatus:
      description: 'The signing status of a contract document.


        - `draft`: The document is being prepared and has not been sent for signing.

        - `awaiting_signatures`: The document has been sent and is waiting for one or more parties to sign.

        - `finished`: All required signatures have been collected and the contract is fully executed.

        '
      enum:
      - draft
      - awaiting_signatures
      - finished
      example: draft
      title: ContractorContractDocumentStatus
      type: string
  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