Deel Subpackage Contractor Hiring API

openapi: 3.2.0
info:
  title: Endpoints Subpackage Contractor Hiring API
  version: 1.0.0
servers:
- url: https://api.letsdeel.com/rest/v2
- url: https://api-staging.letsdeel.com/rest/v2
tags:
- name: subpackage_contractorHiring
paths:
  /contracts/{contract_id}/documents:
    post:
      operationId: create-contract-document
      summary: Attach a file to contract
      description: 'Attach a file to contract document.

        **Token scopes**: `contracts:write`'
      tags:
      - subpackage_contractorHiring
      parameters:
      - name: contract_id
        in: path
        description: Deel contract id.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: "## Authentication\nThe Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail.\n\n```curl\ncurl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \\\n  -H 'Authorization: Bearer YOUR-TOKEN-HERE'\n```\n\n[Learn more about authentication](/api/authentication)\n"
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contractor-hiring_createContractDocument_Response_201'
        '400':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '401':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '403':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '404':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '500':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
      requestBody:
        description: A form to attach a file to contract document.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Upload the file you want to attach to this entry.
  /contracts/{contract_id}/invite:
    get:
      operationId: get-contract-invite
      summary: Get worker invite link
      description: 'Generates and returns a signed invitation URL that allows a worker to review and sign their contract securely. Use this endpoint to initiate or resend the contract signing process after the contract has been created. Requires the contract_id, which is provided during the initial Create Contract workflow.

        **Token scopes**: `contracts:read`'
      tags:
      - subpackage_contractorHiring
      parameters:
      - name: contract_id
        in: path
        description: Deel contract id.
        required: true
        schema:
          type: string
      - name: locale
        in: query
        description: Locale to use for the invite link.
        required: false
        schema:
          type: string
      - name: Authorization
        in: header
        description: "## Authentication\nThe Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail.\n\n```curl\ncurl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \\\n  -H 'Authorization: Bearer YOUR-TOKEN-HERE'\n```\n\n[Learn more about authentication](/api/authentication)\n"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contractor-hiring_getContractInvite_Response_200'
        '400':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '401':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '403':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '404':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '500':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
  /contracts/{contract_id}/preview:
    get:
      operationId: get-contract-preview
      summary: Preview a contract agreement
      description: 'Retrieve an IC and EOR contract agreement content in HTML. If no template is specified, the default or currently assigned template will be used. This endpoint does not support Global Payroll contract type.

        **Token scopes**: `contracts:read`, `worker:read`'
      tags:
      - subpackage_contractorHiring
      parameters:
      - name: contract_id
        in: path
        description: Deel contract id.
        required: true
        schema:
          type: string
      - name: templateId
        in: query
        description: ID of an existing contract template.
        required: false
        schema:
          type: string
          format: uuid
      - name: Authorization
        in: header
        description: "## Authentication\nThe Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail.\n\n```curl\ncurl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \\\n  -H 'Authorization: Bearer YOUR-TOKEN-HERE'\n```\n\n[Learn more about authentication](/api/authentication)\n"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '401':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '403':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '404':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '500':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
  /contracts/{contract_id}/invitations:
    delete:
      operationId: get-contract-invitations
      summary: Remove invite
      description: 'Remove invite in order to re-invite a worker to sign the contract

        **Token scopes**: `contracts:write`'
      tags:
      - subpackage_contractorHiring
      parameters:
      - name: contract_id
        in: path
        description: Deel contract id.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: "## Authentication\nThe Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail.\n\n```curl\ncurl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \\\n  -H 'Authorization: Bearer YOUR-TOKEN-HERE'\n```\n\n[Learn more about authentication](/api/authentication)\n"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contractor-hiring_getContractInvitations_Response_200'
        '400':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '401':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '403':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '404':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '500':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
    post:
      operationId: create-contract-invitation
      summary: Send contract to worker
      description: 'Invite a worker to sign the contract. Worker will be notified via email

        **Token scopes**: `contracts:write`'
      tags:
      - subpackage_contractorHiring
      parameters:
      - name: contract_id
        in: path
        description: Deel contract id.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: "## Authentication\nThe Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail.\n\n```curl\ncurl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \\\n  -H 'Authorization: Bearer YOUR-TOKEN-HERE'\n```\n\n[Learn more about authentication](/api/authentication)\n"
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contractor-hiring_createContractInvitation_Response_201'
        '400':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '401':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '403':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '404':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '500':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/ContractsContractIdInvitationsPostRequestBodyContentApplicationJsonSchemaData'
  /contracts/{contract_id}/payment_cycles:
    get:
      operationId: get-contract-payment-cycles
      summary: Retrieve contractor payment dates
      description: 'Fetches a list of payment dates associated with a specific contract. This endpoint provides information on when contractors are scheduled to be paid, along with the current status of each payment cycle.

        **Token scopes**: `contracts:read`'
      tags:
      - subpackage_contractorHiring
      parameters:
      - name: contract_id
        in: path
        description: The Deel contract ID for which payment dates are being retrieved.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: "## Authentication\nThe Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail.\n\n```curl\ncurl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \\\n  -H 'Authorization: Bearer YOUR-TOKEN-HERE'\n```\n\n[Learn more about authentication](/api/authentication)\n"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response containing contractor payment dates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contractor-hiring_getContractPaymentCycles_Response_200'
        '401':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '403':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
  /contracts/{contract_id}/signatures:
    post:
      operationId: create-contract-signature
      summary: Sign a contract
      description: 'Sign a contract as a client.

        **Token scopes**: `contracts:write`'
      tags:
      - subpackage_contractorHiring
      parameters:
      - name: contract_id
        in: path
        description: Deel contract id.
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: "## Authentication\nThe Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail.\n\n```curl\ncurl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \\\n  -H 'Authorization: Bearer YOUR-TOKEN-HERE'\n```\n\n[Learn more about authentication](/api/authentication)\n"
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/contractor-hiring_createContractSignature_Response_201'
        '400':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '401':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '403':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '404':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
        '500':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/ContractsContractIdSignaturesPostRequestBodyContentApplicationJsonSchemaData'
components:
  schemas:
    contractor-hiring_getContractInvitations_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ContractsContractIdInvitationsDeleteResponsesContentApplicationJsonSchemaData'
      required:
      - data
      title: contractor-hiring_getContractInvitations_Response_200
    ContractsContractIdSignaturesPostRequestBodyContentApplicationJsonSchemaData:
      type: object
      properties:
        client_signature:
          type: string
          description: Signature of client.
        contract_template_id:
          $ref: '#/components/schemas/ContractsContractIdSignaturesPostRequestBodyContentApplicationJsonSchemaDataContractTemplateId'
          description: Please use null to use default Deel contract template; otherwise you can use the template you created and customized. If template ID is not in payload, template stays unchanged.
      required:
      - client_signature
      title: ContractsContractIdSignaturesPostRequestBodyContentApplicationJsonSchemaData
    contractor-hiring_getContractPaymentCycles_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ContractsContractIdPaymentCyclesGetResponsesContentApplicationJsonSchemaDataItems'
      required:
      - data
      title: contractor-hiring_getContractPaymentCycles_Response_200
    ContractsContractIdSignaturesPostResponsesContentApplicationJsonSchemaData:
      type: object
      properties:
        created:
          type: boolean
      required:
      - created
      title: ContractsContractIdSignaturesPostResponsesContentApplicationJsonSchemaData
    contractor-hiring_createContractSignature_Response_201:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ContractsContractIdSignaturesPostResponsesContentApplicationJsonSchemaData'
      required:
      - data
      title: contractor-hiring_createContractSignature_Response_201
    ContractsContractIdInvitationsPostResponsesContentApplicationJsonSchemaData:
      type: object
      properties:
        created:
          type: boolean
      required:
      - created
      title: ContractsContractIdInvitationsPostResponsesContentApplicationJsonSchemaData
    ApiError:
      type: object
      properties:
        message:
          type: string
          description: A description of the returned error
        path:
          type: string
          description: The JSON path where input validation failed
      title: ApiError
    ContractsContractIdInvitationsPostRequestBodyContentApplicationJsonSchemaDataLocale:
      type: string
      enum:
      - en
      - es
      - fr
      - de
      - it
      - pt
      - pl
      - nn
      - nl
      - da
      - deAT
      - fi
      - sv
      - nlBE
      - ja
      default: en
      description: Locale of the email
      title: ContractsContractIdInvitationsPostRequestBodyContentApplicationJsonSchemaDataLocale
    ContractsContractIdInvitationsPostRequestBodyContentApplicationJsonSchemaData:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Worker email
        locale:
          $ref: '#/components/schemas/ContractsContractIdInvitationsPostRequestBodyContentApplicationJsonSchemaDataLocale'
          description: Locale of the email
        message:
          type: string
          description: Message to the worker
      title: ContractsContractIdInvitationsPostRequestBodyContentApplicationJsonSchemaData
    contractor-hiring_getContractInvite_Response_200:
      type: object
      properties:
        data:
          type: string
      required:
      - data
      title: contractor-hiring_getContractInvite_Response_200
    contractor-hiring_createContractDocument_Response_201:
      type: object
      properties:
        data:
          oneOf:
          - $ref: '#/components/schemas/ContractsContractIdDocumentsPostResponsesContentApplicationJsonSchemaData'
          - type: 'null'
          description: This object is used for linking file attachments to your records.
      required:
      - data
      title: contractor-hiring_createContractDocument_Response_201
    ApiErrorContainer:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/ApiErrorRequest'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
      title: ApiErrorContainer
    ContractsContractIdInvitationsDeleteResponsesContentApplicationJsonSchemaData:
      type: object
      properties:
        deleted:
          type: boolean
          description: Confirms the deletion.
      required:
      - deleted
      title: ContractsContractIdInvitationsDeleteResponsesContentApplicationJsonSchemaData
    ContractsContractIdPaymentCyclesGetResponsesContentApplicationJsonSchemaDataItemsStatus:
      type: string
      enum:
      - active
      - upcoming
      - awaiting_payment
      - overdue
      description: The current status of the payment cycle.
      title: ContractsContractIdPaymentCyclesGetResponsesContentApplicationJsonSchemaDataItemsStatus
    contractor-hiring_createContractInvitation_Response_201:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ContractsContractIdInvitationsPostResponsesContentApplicationJsonSchemaData'
      required:
      - data
      title: contractor-hiring_createContractInvitation_Response_201
    ApiErrorRequest:
      type: object
      properties:
        method:
          type: string
          description: The HTTP method of the failed request
        url:
          type: string
          description: The relative URL of the failed request
        status:
          type: number
          format: double
          description: The status code of the response
        api_req_id:
          type: string
          description: The request ID of the failed request
        docs:
          type: string
          description: A link to the official documentation for the requested endpoint resource
        source:
          type: string
          description: The source handler which produced the returned error
        code:
          type: number
          format: double
          description: The code of the source handler which produced the returned error
      title: ApiErrorRequest
    ContractsContractIdSignaturesPostRequestBodyContentApplicationJsonSchemaDataContractTemplateId:
      oneOf:
      - type: number
        format: double
      - type: string
      description: Please use null to use default Deel contract template; otherwise you can use the template you created and customized. If template ID is not in payload, template stays unchanged.
      title: ContractsContractIdSignaturesPostRequestBodyContentApplicationJsonSchemaDataContractTemplateId
    ContractsContractIdDocumentsPostResponsesContentApplicationJsonSchemaData:
      type: object
      properties:
        key:
          type: string
          description: You can call attachments end-point, get key and URL to upload your file.
        filename:
          type: string
          description: Original filename you used to upload using attachments end-point.
      required:
      - key
      - filename
      description: This object is used for linking file attachments to your records.
      title: ContractsContractIdDocumentsPostResponsesContentApplicationJsonSchemaData
    ContractsContractIdPaymentCyclesGetResponsesContentApplicationJsonSchemaDataItems:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the payment.
        status:
          $ref: '#/components/schemas/ContractsContractIdPaymentCyclesGetResponsesContentApplicationJsonSchemaDataItemsStatus'
          description: The current status of the payment cycle.
        due_date:
          type: string
          format: date-time
          description: The date and time when the payment is due.
      required:
      - id
      - status
      - due_date
      title: ContractsContractIdPaymentCyclesGetResponsesContentApplicationJsonSchemaDataItems
  securitySchemes:
    deelToken:
      type: http
      scheme: bearer
      description: "## Authentication\nThe Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail.\n\n```curl\ncurl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \\\n  -H 'Authorization: Bearer YOUR-TOKEN-HERE'\n```\n\n[Learn more about authentication](/api/authentication)\n"
    oauth2:
      type: http
      scheme: bearer
      description: Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/