Deel Contractors API

openapi: 3.1.0
info:
  title: Deel Contractors API
  description: |
    Independent Contractor (IC), Pay-As-You-Go, Milestone, and COR (Contractor of Record)
    APIs covering contract creation, amendments, bulk signing, timesheets, milestones,
    IC invoicing taxes, off-cycle payments, bonuses, expense reimbursements, and onboarding.
  version: '2026-05-25'
  contact:
    name: Deel Developer Support
    url: https://developer.deel.com/api/contractors/introduction

servers:
  - url: https://api.letsdeel.com/rest/v2
    description: Production
  - url: https://api-sandbox.demo.deel.com/rest/v2
    description: Sandbox

security:
  - BearerAuth: []

tags:
  - name: Contractor Hiring
    description: Create and onboard IC, PAYG, milestone, and COR contracts
  - name: Contractor Amendments
    description: Amend active contractor contracts
  - name: Timesheets
    description: Submit, approve, and manage contractor timesheets
  - name: Milestones
    description: Milestone-based contract deliverables
  - name: Off Cycle
    description: One-off payments outside the normal cycle
  - name: IC Invoicing Taxes
    description: Contractor invoicing and tax handling

paths:
  /contracts/ic:
    post:
      operationId: createIcContract
      summary: Create A New Contract
      description: Create an Independent Contractor contract (ongoing, PAYG, milestone, or COR variant).
      tags: [Contractor Hiring]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/IcContractCreate' }
      responses:
        '201':
          description: Contract created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/IcContract' }

  /contracts/{contract_id}/external-id:
    patch:
      operationId: addExternalId
      summary: Add External ID
      description: Attach a client-side external ID to a contract for cross-system reconciliation.
      tags: [Contractor Hiring]
      parameters:
        - { name: contract_id, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [external_id]
              properties:
                external_id: { type: string }
      responses:
        '200': { description: External ID set }

  /contracts/{contract_id}/amendments:
    post:
      operationId: createContractorAmendment
      summary: Create Contractor Amendment
      tags: [Contractor Amendments]
      parameters:
        - { name: contract_id, in: path, required: true, schema: { type: string } }
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ContractorAmendmentCreate' }
      responses:
        '201':
          description: Amendment created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ContractorAmendment' }

  /contracts/{contract_id}/amendments/bulk-sign:
    post:
      operationId: bulkSignAmendments
      summary: Bulk Sign Contracts And Amendments
      description: Sign multiple contract amendments programmatically.
      tags: [Contractor Amendments]
      parameters:
        - { name: contract_id, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amendment_ids]
              properties:
                amendment_ids: { type: array, items: { type: string } }
      responses:
        '200':
          description: Amendments signed
          content:
            application/json:
              schema:
                type: object
                properties:
                  signed_count: { type: integer }

  /timesheets:
    get:
      operationId: getTimesheets
      summary: List Timesheets
      tags: [Timesheets]
      parameters:
        - { name: contract_id, in: query, schema: { type: string } }
        - { name: status, in: query, schema: { type: string, enum: [pending, approved, declined] } }
        - { name: from, in: query, schema: { type: string, format: date } }
        - { name: to, in: query, schema: { type: string, format: date } }
      responses:
        '200':
          description: Timesheets
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Timesheet' } }
    post:
      operationId: createTimesheet
      summary: Create Timesheet
      tags: [Timesheets]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TimesheetCreate' }
      responses:
        '201':
          description: Timesheet created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Timesheet' }

  /timesheets/{timesheet_id}/review:
    post:
      operationId: reviewTimesheet
      summary: Review Timesheet
      description: Approve or decline a contractor timesheet.
      tags: [Timesheets]
      parameters:
        - { name: timesheet_id, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [decision]
              properties:
                decision: { type: string, enum: [approve, decline] }
                notes: { type: string }
      responses:
        '200': { description: Timesheet reviewed }

  /contracts/{contract_id}/milestones:
    get:
      operationId: getMilestones
      summary: List Milestones
      tags: [Milestones]
      parameters:
        - { name: contract_id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Milestones
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Milestone' } }
    post:
      operationId: createMilestone
      summary: Create Milestone
      tags: [Milestones]
      parameters:
        - { name: contract_id, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/MilestoneCreate' }
      responses:
        '201':
          description: Milestone created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Milestone' }

  /off-cycle:
    post:
      operationId: createOffCyclePayment
      summary: Create Off-Cycle Payment
      description: Pay a contractor outside of the normal billing cycle (bonus, expense, ad-hoc).
      tags: [Off Cycle]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/OffCycleCreate' }
      responses:
        '201':
          description: Off-cycle payment created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/OffCyclePayment' }

  /ic-invoicing/taxes/{contract_id}:
    get:
      operationId: getIcInvoicingTaxes
      summary: Retrieve Contractor Invoicing Taxes
      tags: [IC Invoicing Taxes]
      parameters:
        - { name: contract_id, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Tax configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      vat_applicable: { type: boolean }
                      vat_rate: { type: number }
                      tax_residency: { type: string }
                      tax_id: { type: string }

components:
  securitySchemes:
    BearerAuth: { type: http, scheme: bearer, bearerFormat: opaque }
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema: { type: string, format: uuid }
  schemas:
    IcContractCreate:
      type: object
      required: [worker, type, currency, country]
      properties:
        worker:
          type: object
          required: [email, first_name, last_name]
          properties:
            email: { type: string, format: email }
            first_name: { type: string }
            last_name: { type: string }
            country: { type: string }
        type: { type: string, enum: [ongoing_time_based, pay_as_you_go_time_based, milestones, cor] }
        currency: { type: string }
        country: { type: string }
        job_title: { type: string }
        seniority_level_id: { type: string }
        rate: { type: number }
        rate_frequency: { type: string, enum: [hourly, weekly, monthly] }
        start_date: { type: string, format: date }
        end_date: { type: string, format: date }
        scope_of_work: { type: string }
        external_id: { type: string }
    IcContract:
      type: object
      properties:
        id: { type: string }
        type: { type: string }
        status: { type: string }
        worker:
          type: object
          properties:
            id: { type: string }
            email: { type: string, format: email }
        rate: { type: number }
        currency: { type: string }
        country: { type: string }
        start_date: { type: string, format: date }
    ContractorAmendmentCreate:
      type: object
      required: [type, effective_date]
      properties:
        type: { type: string, enum: [rate_change, scope_change, currency_change, term_extension, role_change] }
        effective_date: { type: string, format: date }
        new_rate: { type: number }
        new_currency: { type: string }
        notes: { type: string }
    ContractorAmendment:
      type: object
      properties:
        id: { type: string }
        contract_id: { type: string }
        type: { type: string }
        status: { type: string, enum: [pending, approved, declined, signed, applied] }
        effective_date: { type: string, format: date }
    Timesheet:
      type: object
      properties:
        id: { type: string }
        contract_id: { type: string }
        date: { type: string, format: date }
        hours: { type: number }
        description: { type: string }
        status: { type: string, enum: [pending, approved, declined] }
        submitted_at: { type: string, format: date-time }
    TimesheetCreate:
      type: object
      required: [contract_id, date, hours]
      properties:
        contract_id: { type: string }
        date: { type: string, format: date }
        hours: { type: number }
        description: { type: string }
    Milestone:
      type: object
      properties:
        id: { type: string }
        contract_id: { type: string }
        title: { type: string }
        description: { type: string }
        amount: { type: number }
        currency: { type: string }
        status: { type: string, enum: [pending, in_progress, submitted, approved, paid] }
        due_date: { type: string, format: date }
    MilestoneCreate:
      type: object
      required: [title, amount, currency]
      properties:
        title: { type: string }
        description: { type: string }
        amount: { type: number }
        currency: { type: string }
        due_date: { type: string, format: date }
    OffCycleCreate:
      type: object
      required: [contract_id, amount, currency, reason]
      properties:
        contract_id: { type: string }
        amount: { type: number }
        currency: { type: string }
        reason: { type: string, enum: [bonus, commission, expense, reimbursement, advance, other] }
        notes: { type: string }
    OffCyclePayment:
      type: object
      properties:
        id: { type: string }
        contract_id: { type: string }
        amount: { type: number }
        currency: { type: string }
        reason: { type: string }
        status: { type: string, enum: [pending, processing, paid, failed] }
        created_at: { type: string, format: date-time }