openapi: 3.1.0
info:
  title: Endpoints subpackage_eorJobScopes API
  version: 1.0.0
servers:
- url: https://api.letsdeel.com/rest/v2
- url: https://api-staging.letsdeel.com/rest/v2
tags:
- name: subpackage_eorJobScopes
paths:
  /eor/job-scopes:
    get:
      operationId: get-job-scopes
      summary: List of job scope templates for EOR contracts
      description: "Returns a list of predefined job scope templates for an EOR contract, which can be filtered by team. The list includes both predefined and custom job scope templates belonging to the user's teams.\n **Token scopes**: `organizations:read`"
      tags:
      - subpackage_eorJobScopes
      parameters:
      - name: team
        in: query
        description: Team public id
        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: Successfull response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EorJobScopesGetResponsesContentApplicationJsonSchemaItems'
        '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: Not Found - Organization not linked to profile or no teams found for the organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOfJobScopeTemplatesForEorContractsRequestNotFoundError'
        '500':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
  /eor/job-scopes/validate:
    post:
      operationId: validate-job-scope
      summary: Request job scope validation
      description: "This endpoint allows client to validate job scope description.\n **Token scopes**: `contracts:write`"
      tags:
      - subpackage_eorJobScopes
      parameters:
      - 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/eor-job-scopes_validateJobScope_Response_200'
        '400':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestJobScopeValidation-v2026-01-01RequestBadRequestError'
        '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: Run job scope validation
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/EorJobScopesValidatePostRequestBodyContentApplicationJsonSchemaData'
                  description: details of job scope
              required:
              - data
components:
  schemas:
    EorJobScopesGetResponsesContentApplicationJsonSchemaItemsTeam:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique identifier of the associated team, if any
        name:
          type:
          - string
          - 'null'
          description: Name of the team associated with the job scope, if any
      title: EorJobScopesGetResponsesContentApplicationJsonSchemaItemsTeam
    EorJobScopesValidatePostResponsesContentApplicationJsonSchemaDataForCorrectedJobScopeEndpoint:
      type: object
      properties:
        anonymized_job_scope:
          type:
          - string
          - 'null'
          description: Anonymized job scope.
        errors_for_correct_job_scope:
          type: array
          items:
            $ref: '#/components/schemas/EorJobScopesValidatePostResponsesContentApplicationJsonSchemaDataForCorrectedJobScopeEndpointErrorsForCorrectJobScopeItems'
          description: List of errors for corrected job scope.
        must_create_correct_job_scope:
          type: boolean
          description: Indicates if a corrected job scope is required.
      description: Data for corrected job scope endpoint.
      title: EorJobScopesValidatePostResponsesContentApplicationJsonSchemaDataForCorrectedJobScopeEndpoint
    EorJobScopesValidatePostResponsesContentApplicationJsonSchemaDataForCorrectedJobScopeEndpointErrorsForCorrectJobScopeItems:
      type: object
      properties:
        message:
          type: string
          description: Message with error description
      title: EorJobScopesValidatePostResponsesContentApplicationJsonSchemaDataForCorrectedJobScopeEndpointErrorsForCorrectJobScopeItems
    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
    EorJobScopesGetResponsesContentApplicationJsonSchemaItems:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the job scope
        team:
          $ref: '#/components/schemas/EorJobScopesGetResponsesContentApplicationJsonSchemaItemsTeam'
        title:
          type: string
          description: Title or name of the job scope
        content:
          type: string
          description: Detailed description of the job scope
        personal:
          type:
          - string
          - 'null'
          description: Identifier from the team or the profile, whichever is available
        created_at:
          type: string
          description: Timestamp of when the job scope was created
        created_by:
          $ref: '#/components/schemas/EorJobScopesGetResponsesContentApplicationJsonSchemaItemsCreatedBy'
        updated_at:
          type: string
          description: Timestamp of when the job scope was last updated
        updated_by:
          $ref: '#/components/schemas/EorJobScopesGetResponsesContentApplicationJsonSchemaItemsUpdatedBy'
        source_type:
          $ref: '#/components/schemas/EorJobScopesGetResponsesContentApplicationJsonSchemaItemsSourceType'
          description: Source of the job scope data
        organization_id:
          type:
          - string
          - 'null'
          description: Identifier of the associated organization, if any
      title: EorJobScopesGetResponsesContentApplicationJsonSchemaItems
    ListOfJobScopeTemplatesForEorContractsRequestNotFoundError:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/EorJobScopesGetResponsesContentApplicationJsonSchemaError'
          description: Error message indicating the missing entity
      title: ListOfJobScopeTemplatesForEorContractsRequestNotFoundError
    RequestJobScopeValidation-v2026-01-01RequestBadRequestError:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/EorJobScopesValidatePostResponsesContentApplicationJsonSchemaErrorsItems'
        request:
          $ref: '#/components/schemas/EorJobScopesValidatePostResponsesContentApplicationJsonSchemaRequest'
      title: RequestJobScopeValidation-v2026-01-01RequestBadRequestError
    EorJobScopesValidatePostRequestBodyContentApplicationJsonSchemaData:
      type: object
      properties:
        team_id:
          type: string
          format: uuid
          description: The ID of the team.
        job_scope:
          type: string
          description: The scope of the job.
        job_title:
          type: string
          description: The title of the job.
        work_visa:
          type: boolean
          description: Indicates if a work visa is required.
        client_name:
          type: string
          description: Optional client name. The validation refuses a job scope if it includes the client name. If not provided, it will be inferred from the legal entity instead.
        employee_name:
          type: string
          description: The name of the employee.
        special_job_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the special job.
        employment_state:
          type:
          - string
          - 'null'
          description: The state of employment.
        employment_country:
          type: string
          description: The country of employment.
        employee_nationality:
          type: string
          description: The nationality of the employee.
        client_legal_entity_id:
          type: string
          format: uuid
          description: The ID of the client's legal entity.
      required:
      - team_id
      - job_scope
      - job_title
      - employee_name
      - employment_country
      - client_legal_entity_id
      description: details of job scope
      title: EorJobScopesValidatePostRequestBodyContentApplicationJsonSchemaData
    EorJobScopesValidatePostResponsesContentApplicationJsonSchemaErrorsItems:
      type: object
      properties:
        path:
          type: string
          description: The JSON path where input validation failed
        message:
          type: string
          description: A description of the returned error
      title: EorJobScopesValidatePostResponsesContentApplicationJsonSchemaErrorsItems
    eor-job-scopes_validateJobScope_Response_200:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/EorJobScopesValidatePostResponsesContentApplicationJsonSchemaErrorsItems'
          description: List of validation errors, if empty the validation was successfully.
        quote_validation_log_public_id:
          type: string
          description: Id from validation request.
        data_for_corrected_job_scope_endpoint:
          $ref: '#/components/schemas/EorJobScopesValidatePostResponsesContentApplicationJsonSchemaDataForCorrectedJobScopeEndpoint'
          description: Data for corrected job scope endpoint.
      title: eor-job-scopes_validateJobScope_Response_200
    EorJobScopesGetResponsesContentApplicationJsonSchemaItemsSourceType:
      type: string
      enum:
      - MANUAL
      - AI
      description: Source of the job scope data
      title: EorJobScopesGetResponsesContentApplicationJsonSchemaItemsSourceType
    EorJobScopesGetResponsesContentApplicationJsonSchemaError:
      type: string
      enum:
      - No organization is linked with the profile
      - No teams found for this organization
      description: Error message indicating the missing entity
      title: EorJobScopesGetResponsesContentApplicationJsonSchemaError
    ApiErrorContainer:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/ApiErrorRequest'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
      title: ApiErrorContainer
    EorJobScopesValidatePostResponsesContentApplicationJsonSchemaRequest:
      type: object
      properties:
        url:
          type: string
          description: The relative URL of the failed request
        code:
          type: number
          format: double
          description: The code of the source handler which produced the returned error
        docs:
          type: string
          description: A link to the official documentation for the requested endpoint resource
        method:
          type: string
          description: The HTTP method of the failed request
        source:
          type: string
          description: The source handler which produced the returned error
        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
      title: EorJobScopesValidatePostResponsesContentApplicationJsonSchemaRequest
    EorJobScopesGetResponsesContentApplicationJsonSchemaItemsCreatedBy:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique identifier of the user who created the job scope
        name:
          type:
          - string
          - 'null'
          description: Name of the user who created the job scope
      title: EorJobScopesGetResponsesContentApplicationJsonSchemaItemsCreatedBy
    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
    EorJobScopesGetResponsesContentApplicationJsonSchemaItemsUpdatedBy:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Unique identifier of the user who last updated the job scope
        name:
          type:
          - string
          - 'null'
          description: Name of the user who last updated the job scope
      title: EorJobScopesGetResponsesContentApplicationJsonSchemaItemsUpdatedBy
  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/