openapi: 3.1.0
info:
  title: Endpoints subpackage_lookups API
  version: 1.0.0
servers:
- url: https://api.letsdeel.com/rest/v2
- url: https://api-staging.letsdeel.com/rest/v2
tags:
- name: subpackage_lookups
paths:
  /lookups/job-titles:
    get:
      operationId: get-job-titles
      summary: Job titles list
      description: Retrieve a list of pre-defined job titles in Deel platform.
      tags:
      - subpackage_lookups
      parameters:
      - name: after_cursor
        in: query
        description: Cursor for pagination. Use this to retrieve the next page of results.
        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/lookups_getJobTitles_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'
  /lookups/countries:
    get:
      operationId: get-countries
      summary: Retrieve Country List
      description: Retrieve a list of countries supported by Deel, along with details about visa and EoR support, sub-territories, and their classifications.
      tags:
      - subpackage_lookups
      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/lookups_getCountries_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'
  /lookups/seniorities:
    get:
      operationId: get-seniority-levels
      summary: Retrieve Seniority Levels
      description: Retrieve a list of predefined seniority levels for roles in the Deel platform, including their names, hierarchical levels, and unique identifiers.
      tags:
      - subpackage_lookups
      parameters:
      - name: is_eor_contract
        in: query
        description: when `true`, exclude C-level seniorities for EOR contracts. Set to `false` to return all seniorities
        required: false
        schema:
          type: boolean
          default: true
      - 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/lookups_getSeniorityLevels_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'
  /lookups/currencies:
    get:
      operationId: get-currencies
      summary: Retrieve Supported Currency List
      description: Retrieve the list of currencies supported by Deel, including their ISO codes and names
      tags:
      - subpackage_lookups
      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/lookups_getCurrencies_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'
  /lookups/time-off-types:
    get:
      operationId: get-time-off-types
      summary: Retrieve Time-Off Types
      description: Retrieve a list of predefined time-off types that can be registered in the Deel platform.
      tags:
      - subpackage_lookups
      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/lookups_getTimeOffTypes_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: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveTimeOffTypesRequestNotFoundError'
        '500':
          description: Operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorContainer'
  /lookups:
    get:
      operationId: get-lookups
      summary: Retrieve lookup information for currencies, countries, entity types, etc
      description: "Retrieve lookup information such as currencies, countries, entity types, or SIC numbers. Use the `type` query parameter to specify which data to retrieve.\n **Token scopes**: `legal-entity:read`"
      tags:
      - subpackage_lookups
      parameters:
      - name: documents
        in: query
        description: The type of lookup data to retrieve. Options are `currencies`, `countries`, `entity_types`, and `sic_numbers`.
        required: true
        schema:
          $ref: '#/components/schemas/LookupsGetParametersDocuments'
      - 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 list of lookup information based on the requested type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lookups_getLookups_Response_200'
        '400':
          description: Invalid request parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLookupsRequestBadRequestError'
        '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'
components:
  schemas:
    LookupsCurrenciesGetResponsesContentApplicationJsonSchemaDataItems:
      type: object
      properties:
        code:
          type: string
          description: The ISO 4217 three-letter currency code.
        name:
          type:
          - string
          - 'null'
          description: The name of the currency. This may be null if a name is not available.
      required:
      - code
      title: LookupsCurrenciesGetResponsesContentApplicationJsonSchemaDataItems
    lookups_getTimeOffTypes_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/LookupsTimeOffTypesGetResponsesContentApplicationJsonSchemaDataItems'
          description: List of predefined time-off types supported by the Deel platform.
      title: lookups_getTimeOffTypes_Response_200
    LookupsCountriesGetResponsesContentApplicationJsonSchemaDataItemsStatesItems:
      type: object
      properties:
        code:
          type: string
          description: The code representing the sub-territory (e.g., state or region).
        name:
          type: string
          description: The name of the sub-territory (e.g., state or region).
      required:
      - code
      - name
      title: LookupsCountriesGetResponsesContentApplicationJsonSchemaDataItemsStatesItems
    LookupsGetResponsesContentApplicationJsonSchemaDataItems:
      type: object
      properties:
        label:
          type: string
          description: The label for the lookup item (e.g., country name, entity type).
        value:
          type: string
          description: The value associated with the lookup item (e.g., ISO code, type identifier).
      title: LookupsGetResponsesContentApplicationJsonSchemaDataItems
    LookupsJobTitlesGetResponsesContentApplicationJsonSchemaDataItems:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: identifier of the job title
        name:
          type: string
          description: Job title.
      required:
      - id
      - name
      title: LookupsJobTitlesGetResponsesContentApplicationJsonSchemaDataItems
    LookupsGetParametersDocuments:
      type: string
      enum:
      - sicNumbers
      - entityTypes
      - countries
      title: LookupsGetParametersDocuments
    LookupsCountriesGetResponsesContentApplicationJsonSchemaDataItems:
      type: object
      properties:
        code:
          type: string
          description: The ISO 3166-1 alpha-2 country code.
        name:
          type: string
          description: The official name of the country.
        states:
          type: array
          items:
            $ref: '#/components/schemas/LookupsCountriesGetResponsesContentApplicationJsonSchemaDataItemsStatesItems'
          description: List of sub-territories within the country. These may be called states, provinces, prefectures, regions, or may not exist.
        state_type:
          type:
          - string
          - 'null'
          description: The designation for sub-territories within the country, such as 'state', 'province', 'prefecture', or 'region'. If none, this field will be null.
        eor_support:
          type: boolean
          description: Indicates whether Deel provides Employer of Record (EoR) support in this country.
        visa_support:
          type: boolean
          description: Indicates whether Deel provides visa support for employees being hired in this country.
        default_currency:
          type: string
          description: Indicates the default currency 3-letter ISO code
      required:
      - code
      - name
      - states
      - state_type
      - eor_support
      - visa_support
      - default_currency
      title: LookupsCountriesGetResponsesContentApplicationJsonSchemaDataItems
    lookups_getJobTitles_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/LookupsJobTitlesGetResponsesContentApplicationJsonSchemaDataItems'
        page:
          $ref: '#/components/schemas/LookupsJobTitlesGetResponsesContentApplicationJsonSchemaPage'
      title: lookups_getJobTitles_Response_200
    GetLookupsRequestBadRequestError:
      type: object
      properties:
        message:
          type: string
          description: Error message explaining what went wrong.
      title: GetLookupsRequestBadRequestError
    LookupsTimeOffTypesGetResponsesContentApplicationJsonSchemaDataItems:
      type: string
      enum:
      - VACATION
      - SICK_LEAVE
      - OTHER
      - UNPAID_LEAVE
      description: Predefined time-off types. Possible values include 'VACATION', 'SICK_LEAVE', 'UNPAID_LEAVE'  and 'OTHER'.
      title: LookupsTimeOffTypesGetResponsesContentApplicationJsonSchemaDataItems
    lookups_getCurrencies_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/LookupsCurrenciesGetResponsesContentApplicationJsonSchemaDataItems'
          description: List of currencies supported by Deel.
      title: lookups_getCurrencies_Response_200
    RetrieveTimeOffTypesRequestNotFoundError:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/LookupsTimeOffTypesGetResponsesContentApplicationJsonSchemaErrorsItems'
          description: Array of error objects containing error messages.
      required:
      - errors
      title: RetrieveTimeOffTypesRequestNotFoundError
    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
    LookupsSenioritiesGetResponsesContentApplicationJsonSchemaDataItems:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: A unique identifier for the seniority level.
        name:
          type: string
          description: The name of the seniority level, e.g., 'Mid (Individual Contributor Level 2)'.
        level:
          type:
          - number
          - 'null'
          format: double
          description: The hierarchical level of seniority, where higher numbers indicate greater seniority.
      required:
      - id
      - name
      title: LookupsSenioritiesGetResponsesContentApplicationJsonSchemaDataItems
    lookups_getSeniorityLevels_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/LookupsSenioritiesGetResponsesContentApplicationJsonSchemaDataItems'
          description: List of predefined seniority levels supported by the Deel platform.
      title: lookups_getSeniorityLevels_Response_200
    lookups_getCountries_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/LookupsCountriesGetResponsesContentApplicationJsonSchemaDataItems'
      title: lookups_getCountries_Response_200
    LookupsJobTitlesGetResponsesContentApplicationJsonSchemaPage:
      type: object
      properties:
        cursor:
          type: string
          description: Use for pagination to get next set of records after the given cursor.
      required:
      - cursor
      title: LookupsJobTitlesGetResponsesContentApplicationJsonSchemaPage
    ApiErrorContainer:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/ApiErrorRequest'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
      title: ApiErrorContainer
    Lookups_getLookups_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/LookupsGetResponsesContentApplicationJsonSchemaDataItems'
      title: Lookups_getLookups_Response_200
    LookupsTimeOffTypesGetResponsesContentApplicationJsonSchemaErrorsItems:
      type: object
      properties:
        message:
          type: string
          description: Error message describing what went wrong.
      required:
      - message
      title: LookupsTimeOffTypesGetResponsesContentApplicationJsonSchemaErrorsItems
    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
  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/