> ## Documentation Index > Fetch the complete documentation index at: https://docs.spott.io/llms.txt > Use this file to discover all available pages before exploring further. # Search candidates > Retrieve a paginated list of candidates filtered by supported predefined candidate fields and candidate custom attributes. ## OpenAPI ````yaml /api-reference/openapi.json post /candidates/_search openapi: 3.1.0 info: title: Spott API Reference version: '0.1' servers: - url: https://api.gospott.com security: [] tags: [] paths: /candidates/_search: post: tags: - Candidates summary: Search candidates description: >- Retrieve a paginated list of candidates filtered by supported predefined candidate fields and candidate custom attributes. operationId: searchCandidates parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchCandidatesRequestDto' responses: '200': description: Candidates retrieved successfully content: application/json: schema: $ref: '#/components/schemas/SearchCandidatesResponseDto' headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' '400': description: Bad request - invalid search parameters content: application/json: schema: $ref: '#/components/schemas/ExceptionBaseDto' headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' '401': description: Unauthorized - invalid or missing authentication content: application/json: schema: $ref: '#/components/schemas/ExceptionBaseDto' headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/GlobalNotFoundApiErrorDto' headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/GlobalConflictApiErrorDto' headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' '429': description: >- Too Many Requests. The published limit for this endpoint is 600 requests per minute per workspace. The limit in force for your workspace can differ from it in either direction — a workspace on a free trial can be capped lower, and a higher limit can be arranged through support — so the headers, not this number, are authoritative. Read the RateLimit-Policy response header for the quota actually in force and RateLimit for what is left of the current window; on a 429, Retry-After gives the seconds to wait. content: application/json: schema: $ref: '#/components/schemas/ExceptionBaseDto' headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Retry-After: $ref: '#/components/headers/Retry-After' '500': description: Error response content: application/json: schema: $ref: '#/components/schemas/InternalServerErrorDto' headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' security: - x-api-key: [] components: schemas: SearchCandidatesRequestDto: type: object properties: filters: maxItems: 100 type: array items: $ref: '#/components/schemas/AppliedCandidateFilterDto' page: type: integer minimum: 0 maximum: 9007199254740991 pageSize: type: integer minimum: 1 maximum: 100 SearchCandidatesResponseDto: type: object properties: items: type: array items: $ref: '#/components/schemas/CandidateBaseDto' pagination: $ref: '#/components/schemas/SearchCandidatesPaginationDto' required: - items - pagination ExceptionBaseDto: type: object properties: status: type: integer minimum: -9007199254740991 maximum: 9007199254740991 category: $ref: '#/components/schemas/ApiErrorCategoryDto' message: type: string requestId: type: string required: - status - message - requestId GlobalNotFoundApiErrorDto: anyOf: - $ref: '#/components/schemas/ResourceNotFoundApiErrorDto' - $ref: '#/components/schemas/RelatedResourceNotFoundApiErrorDto' GlobalConflictApiErrorDto: anyOf: - $ref: '#/components/schemas/ResourceAlreadyExistsApiErrorDto' - $ref: '#/components/schemas/ResourceLockTimeoutApiErrorDto' InternalServerErrorDto: type: object properties: status: type: number const: 500 category: type: string enum: - INTERNAL_ERROR message: type: string enum: - Internal server error requestId: type: string required: - status - category - message - requestId AppliedCandidateFilterDto: anyOf: - $ref: '#/components/schemas/AppliedCandidateTextFilterDto' - $ref: '#/components/schemas/AppliedCandidateLocationTextFilterDto' - $ref: '#/components/schemas/AppliedCandidateEmptyTextFilterDto' - $ref: '#/components/schemas/AppliedCandidateEntitySelectFilterDto' - $ref: '#/components/schemas/AppliedCandidateDateFilterDto' - $ref: '#/components/schemas/AppliedCandidateDateRangeFilterDto' - $ref: '#/components/schemas/AppliedCandidateCustomTextFilterDto' - $ref: '#/components/schemas/AppliedCandidateCustomDateFilterDto' - $ref: '#/components/schemas/AppliedCandidateCustomEmptyDateFilterDto' - $ref: '#/components/schemas/AppliedCandidateCustomDateRangeFilterDto' - $ref: '#/components/schemas/AppliedCandidateCustomNumberFilterDto' - $ref: '#/components/schemas/AppliedCandidateCustomNumberRangeFilterDto' - $ref: '#/components/schemas/AppliedCandidateCustomEntitySelectFilterDto' - $ref: >- #/components/schemas/AppliedCandidateCustomEntityMultiSelectFilterDto - $ref: '#/components/schemas/AppliedCandidateCustomBooleanFilterDto' - $ref: '#/components/schemas/AppliedCandidateCustomEnumSelectFilterDto' - $ref: '#/components/schemas/AppliedCandidateCustomEnumListSelectFilterDto' - $ref: '#/components/schemas/AppliedCandidateCustomCurrencyFilterDto' - $ref: '#/components/schemas/AppliedCandidateCustomDurationFilterDto' - $ref: '#/components/schemas/AppliedCandidateCustomUrlFilterDto' - $ref: '#/components/schemas/AppliedCandidateCustomTimeStampFilterDto' - $ref: '#/components/schemas/AppliedCandidateCustomRatingFilterDto' - $ref: '#/components/schemas/AppliedCandidateCustomRatingRangeFilterDto' CandidateBaseDto: type: object properties: id: type: string minLength: 1 name: type: object properties: viewType: type: string enum: - candidateName avatarUrl: type: - string - 'null' firstName: type: string lastName: type: string required: - viewType - avatarUrl - firstName - lastName gender: type: object properties: viewType: type: string enum: - candidateGender gender: type: - string - 'null' enum: - male - female - x - null required: - viewType - gender nationality: type: object properties: viewType: type: string enum: - candidateNationality nationality: type: array items: type: string enum: - Afghan - Albanian - Algerian - American - Andorran - Angolan - Antiguan - Argentinean - Armenian - Australian - Austrian - Azerbaijani - Bahamian - Bahraini - Bangladeshi - Barbadian - Barbudan - Batswana - Belarusian - Belgian - Belizean - Beninese - Bhutanese - Bolivian - Bosnian - Brazilian - British - Bruneian - Bulgarian - Burkinabe - Burmese - Burundian - Cambodian - Cameroonian - Canadian - Cape Verdean - Central African - Chadian - Chilean - Chinese - Colombian - Comoran - Congolese - Costa Rican - Croatian - Cuban - Cypriot - Czech - Danish - Djibouti - Dominican - Dutch - East Timorese - Ecuadorean - Egyptian - Emirian - Equatorial Guinean - Eritrean - Estonian - Ethiopian - Fijian - Filipino - Finnish - French - Gabonese - Gambian - Georgian - German - Ghanaian - Greek - Grenadian - Guatemalan - Guinea-Bissauan - Guinean - Guyanese - Haitian - Herzegovinian - Honduran - Hungarian - I-Kiribati - Icelander - Indian - Indonesian - Iranian - Iraqi - Irish - Israeli - Italian - Ivorian - Jamaican - Japanese - Jordanian - Kazakhstani - Kenyan - Kittian and Nevisian - Kosovar - Kuwaiti - Kyrgyz - Laotian - Latvian - Lebanese - Liberian - Libyan - Liechtensteiner - Lithuanian - Luxembourger - Macedonian - Malagasy - Malawian - Malaysian - Maldivian - Malian - Maltese - Marshallese - Mauritanian - Mauritian - Mexican - Micronesian - Moldovan - Monacan - Mongolian - Moroccan - Mosotho - Motswana - Mozambican - Namibian - Nauruan - Nepalese - New Zealander - Ni-Vanuatu - Nicaraguan - Nigerian - Nigerien - North Korean - Northern Irish - Norwegian - Omani - Pakistani - Palauan - Panamanian - Papua New Guinean - Paraguayan - Peruvian - Polish - Portuguese - Qatari - Romanian - Russian - Rwandan - Saint Lucian - Salvadoran - Samoan - San Marinese - Sao Tomean - Saudi - Scottish - Senegalese - Serbian - Seychellois - Sierra Leonean - Singaporean - Slovakian - Slovenian - Solomon Islander - Somali - South African - South Korean - Spanish - Sri Lankan - Sudanese - Surinamer - Swazi - Swedish - Swiss - Syrian - Taiwanese - Tajik - Tanzanian - Thai - Togolese - Tongan - Trinidadian or Tobagonian - Tunisian - Turkish - Turkmenistani - Tuvaluan - Ugandan - Ukrainian - Uruguayan - Uzbekistani - Venezuelan - Vietnamese - Welsh - Yemenite - Zambian - Zimbabwean required: - viewType - nationality status: type: object properties: viewType: type: string enum: - candidateStatus status: type: array items: type: string enum: - actively_looking - approachable_but_not_actively_looking - do_not_contact - do_not_poach - not_actively_looking required: - viewType - status emails: type: object properties: viewType: type: string enum: - candidateEmails emails: type: array items: type: object properties: email: type: string purpose: type: - string - 'null' enum: - personal - work - null isPrimary: type: boolean required: - email - purpose - isPrimary required: - viewType - emails phoneNumbers: type: object properties: viewType: type: string enum: - candidatePhoneNumbers phoneNumbers: type: array items: type: object properties: phoneNumber: type: string purpose: type: - string - 'null' enum: - personal - work - null isPrimary: type: boolean required: - phoneNumber - purpose - isPrimary required: - viewType - phoneNumbers locations: type: object properties: viewType: type: string enum: - candidateLocation locations: type: array items: $ref: '#/components/schemas/LocationDto' required: - viewType - locations dateOfBirth: type: object properties: viewType: type: string enum: - candidateDateOfBirth dateOfBirth: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' required: - viewType - dateOfBirth socialMedia: type: object properties: viewType: type: string enum: - candidateSocialMedia socialMedia: type: array items: type: object properties: url: type: string type: type: string enum: - LINKEDIN - TWITTER - FACEBOOK - INSTAGRAM isPrimary: type: boolean required: - url - type - isPrimary required: - viewType - socialMedia lastInteractionDate: type: object properties: viewType: type: string enum: - candidateLastInteractionDate lastInteractionDate: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' required: - viewType - lastInteractionDate lastInteractionWith: type: object properties: viewType: type: string enum: - candidateLastInteractionWith user: anyOf: - $ref: '#/components/schemas/UserDto' - type: 'null' required: - viewType - user nextInteractionDate: type: object properties: viewType: type: string enum: - candidateNextInteractionDate nextInteractionDate: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' required: - viewType - nextInteractionDate nextInteractionWith: type: object properties: viewType: type: string enum: - candidateNextInteractionWith user: anyOf: - $ref: '#/components/schemas/UserDto' - type: 'null' required: - viewType - user mainContact: type: object properties: viewType: type: string enum: - candidateMainContact user: anyOf: - $ref: '#/components/schemas/UserDto' - type: 'null' required: - viewType - user team: anyOf: - $ref: '#/components/schemas/TeamBadgeDto' - type: 'null' languages: type: object properties: viewType: type: string enum: - candidateLanguages languages: type: array items: $ref: '#/components/schemas/LanguageDto' required: - viewType - languages compensation: type: object properties: viewType: type: string enum: - candidateCompensation compensation: anyOf: - $ref: '#/components/schemas/CompensationDto' - type: 'null' required: - viewType - compensation currentPlacements: type: object properties: viewType: type: string enum: - candidateCurrentPlacements hasCurrentPlacement: type: boolean placements: type: array items: type: object properties: id: type: string company: type: object properties: id: type: string name: type: string logoUrl: type: - string - 'null' required: - id - name - logoUrl startDate: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' endDate: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' required: - id - company - startDate - endDate required: - viewType - hasCurrentPlacement - placements nextTaskDue: type: object properties: viewType: type: string enum: - candidateNextTaskDue nextTaskDue: anyOf: - $ref: '#/components/schemas/NextTaskDueDto' - type: 'null' required: - viewType - nextTaskDue createdAt: $ref: '#/components/schemas/DateISO' modifiedAt: $ref: '#/components/schemas/DateISO' lastActivityDate: $ref: '#/components/schemas/DateISO' acquisitionSource: anyOf: - type: object properties: viewType: type: string enum: - candidateAcquisitionSource acquisitionSource: type: - string - 'null' enum: - manual - cv_parse - inbound_vacancy_portal - inbound_spontaneous_application - chrome_extension_linkedin - inbound_from_linkedin_jobboard_email - inbound_from_external_jobboard - juicebox - pin - maildrop - csv_import - vdab - advertsdata - null required: - viewType - acquisitionSource - type: 'null' latestWorkExperience: anyOf: - $ref: '#/components/schemas/WorkExperienceBadgeDto' - type: 'null' customAttributes: type: array items: $ref: '#/components/schemas/CustomAttributeItemDto' aiSummary: type: - string - 'null' isVisibleIfClientContact: type: - boolean - 'null' skills: type: array items: $ref: '#/components/schemas/SkillBadgeDto' required: - id - name - gender - nationality - status - emails - phoneNumbers - locations - dateOfBirth - socialMedia - lastInteractionDate - lastInteractionWith - nextInteractionDate - nextInteractionWith - mainContact - team - languages - compensation - currentPlacements - nextTaskDue - createdAt - modifiedAt - lastActivityDate - acquisitionSource - latestWorkExperience - customAttributes - aiSummary - isVisibleIfClientContact SearchCandidatesPaginationDto: type: object properties: hasNextPage: type: boolean required: - hasNextPage ApiErrorCategoryDto: type: string enum: - MALFORMED_REQUEST - SCHEMA_VALIDATION_FAILED - DOMAIN_VALIDATION_FAILED - OPERATION_LIMIT_EXCEEDED - AUTHENTICATION_REQUIRED - AUTHENTICATION_FAILED - SECURITY_CHALLENGE_REQUIRED - SECURITY_CHALLENGE_FAILED - PERMISSION_DENIED - ENTITLEMENT_REQUIRED - PROVIDER_AUTHENTICATION_REQUIRED - PROVIDER_AUTHENTICATION_FAILED - CONFIGURATION_REQUIRED - RESOURCE_NOT_FOUND - RESOURCE_ALREADY_EXISTS - RESOURCE_EXPIRED - RESOURCE_BUSY - RESOURCE_STATE_CONFLICT - QUOTA_EXCEEDED - RATE_LIMITED - UNSUPPORTED_OPERATION - UPSTREAM_REJECTED - TIMEOUT - TEMPORARILY_UNAVAILABLE - INTERNAL_ERROR ResourceNotFoundApiErrorDto: type: object properties: status: type: number const: 404 category: type: string enum: - RESOURCE_NOT_FOUND message: type: string enum: - Resource not found requestId: type: string required: - status - category - message - requestId RelatedResourceNotFoundApiErrorDto: type: object properties: status: type: number const: 404 category: type: string enum: - RESOURCE_NOT_FOUND message: type: string enum: - Related resource not found requestId: type: string required: - status - category - message - requestId ResourceAlreadyExistsApiErrorDto: type: object properties: status: type: number const: 409 category: type: string enum: - RESOURCE_ALREADY_EXISTS message: type: string enum: - Resource already exists requestId: type: string required: - status - category - message - requestId ResourceLockTimeoutApiErrorDto: type: object properties: status: type: number const: 409 category: type: string enum: - RESOURCE_BUSY message: type: string enum: - >- Lock could not be acquired for this resource, please try again later. requestId: type: string required: - status - category - message - requestId AppliedCandidateTextFilterDto: type: object properties: type: type: string enum: - text operator: type: string enum: - contains - equals - startsWith - notEquals path: type: string enum: - candidate.firstName - candidate.lastName value: type: string required: - type - operator - path - value AppliedCandidateLocationTextFilterDto: type: object properties: type: type: string enum: - text operator: type: string enum: - equals - startsWith - notEquals path: type: string enum: - candidate.location.postalCode value: type: string required: - type - operator - path - value AppliedCandidateEmptyTextFilterDto: type: object properties: type: type: string enum: - text operator: type: string enum: - isEmpty - isNotEmpty path: type: string enum: - candidate.emailAddresses - candidate.phoneNumbers - candidate.linkedInUrl required: - type - operator - path AppliedCandidateEntitySelectFilterDto: type: object properties: type: type: string enum: - entitySelect operator: type: string enum: - in - notIn path: type: string enum: - candidate.mainContact value: type: - string - 'null' required: - type - operator - path - value AppliedCandidateDateFilterDto: type: object properties: type: type: string enum: - date operator: type: string enum: - equals - notEquals - lessThanOrEqual - greaterThanOrEqual path: type: string enum: - candidate.createdAt value: $ref: '#/components/schemas/DateISO' required: - type - operator - path - value AppliedCandidateDateRangeFilterDto: type: object properties: type: type: string enum: - dateRange operator: type: string enum: - between path: type: string enum: - candidate.createdAt value: type: object properties: from: $ref: '#/components/schemas/DateISO' to: $ref: '#/components/schemas/DateISO' required: - from - to required: - type - operator - path - value AppliedCandidateCustomTextFilterDto: type: object properties: type: type: string enum: - text operator: type: string enum: - contains - equals - startsWith - notEquals path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: type: string required: - type - operator - path - value AppliedCandidateCustomDateFilterDto: type: object properties: type: type: string enum: - date operator: type: string enum: - lessThanOrEqual - greaterThanOrEqual - equals - notEquals path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: $ref: '#/components/schemas/DateISO' required: - type - operator - path - value AppliedCandidateCustomEmptyDateFilterDto: type: object properties: type: type: string enum: - date operator: type: string enum: - isEmpty - isNotEmpty path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' required: - type - operator - path AppliedCandidateCustomDateRangeFilterDto: type: object properties: type: type: string enum: - date operator: type: string enum: - between path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: type: object properties: from: $ref: '#/components/schemas/DateISO' to: $ref: '#/components/schemas/DateISO' required: - from - to required: - type - operator - path - value AppliedCandidateCustomNumberFilterDto: type: object properties: type: type: string enum: - number operator: type: string enum: - greaterThanOrEqual - lessThanOrEqual path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: type: number required: - type - operator - path - value AppliedCandidateCustomNumberRangeFilterDto: type: object properties: type: type: string enum: - number operator: type: string enum: - between path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: type: object properties: from: type: number to: type: number required: - from - to required: - type - operator - path - value AppliedCandidateCustomEntitySelectFilterDto: type: object properties: type: type: string enum: - entitySelect operator: type: string enum: - in - notIn path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: type: - string - 'null' required: - type - operator - path - value AppliedCandidateCustomEntityMultiSelectFilterDto: type: object properties: type: type: string enum: - entitySelect operator: type: string enum: - in - notIn - isAllOf path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: maxItems: 100 type: array items: type: - string - 'null' required: - type - operator - path - value AppliedCandidateCustomBooleanFilterDto: type: object properties: type: type: string enum: - boolean operator: type: string enum: - equals - notEquals path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: type: boolean required: - type - operator - path - value AppliedCandidateCustomEnumSelectFilterDto: type: object properties: type: type: string enum: - enumSelect operator: type: string enum: - in - notIn - isAllOf path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: maxItems: 100 type: array items: type: - string - 'null' required: - type - operator - path - value AppliedCandidateCustomEnumListSelectFilterDto: type: object properties: type: type: string enum: - enumListSelect operator: type: string enum: - contains - doesNotContain path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: type: - string - 'null' required: - type - operator - path - value AppliedCandidateCustomCurrencyFilterDto: type: object properties: type: type: string enum: - currency operator: type: string enum: - greaterThanOrEqual - lessThanOrEqual path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: type: object properties: amount: type: number currency: $ref: '#/components/schemas/DmCurrency' required: - amount - currency required: - type - operator - path - value AppliedCandidateCustomDurationFilterDto: type: object properties: type: type: string enum: - duration operator: type: string enum: - greaterThanOrEqual - lessThanOrEqual path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: type: number required: - type - operator - path - value AppliedCandidateCustomUrlFilterDto: type: object properties: type: type: string enum: - url operator: type: string enum: - equals - notEquals - contains - startsWith path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: type: string required: - type - operator - path - value AppliedCandidateCustomTimeStampFilterDto: type: object properties: type: type: string enum: - timestamp operator: type: string enum: - greaterThanOrEqual - lessThanOrEqual path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: $ref: '#/components/schemas/DateISO' required: - type - operator - path - value AppliedCandidateCustomRatingFilterDto: type: object properties: type: type: string enum: - rating operator: type: string enum: - greaterThanOrEqual - lessThanOrEqual - equals path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: type: number required: - type - operator - path - value AppliedCandidateCustomRatingRangeFilterDto: type: object properties: type: type: string enum: - rating operator: type: string enum: - between path: $ref: '#/components/schemas/CandidateCustomAttributePathDto' value: type: object properties: from: type: number to: type: number required: - from - to required: - type - operator - path - value LocationDto: type: object properties: street1: type: - string - 'null' street2: type: - string - 'null' postalCode: type: - string - 'null' city: type: - string - 'null' region: type: - string - 'null' state: type: - string - 'null' country: deprecated: true description: 'Deprecated: use `countryCode` instead.' type: - string - 'null' countryCode: anyOf: - $ref: '#/components/schemas/CountryCode' - type: 'null' rawCityCountry: type: - string - 'null' latitude: type: - number - 'null' longitude: type: - number - 'null' formattedAddress: type: - string - 'null' type: anyOf: - $ref: '#/components/schemas/LocationType' - type: 'null' required: - street1 - street2 - postalCode - city - region - state - country - countryCode - rawCityCountry - latitude - longitude - formattedAddress - type DateISO: format: date-time anyOf: - type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ - type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ UserDto: type: object properties: userId: type: string name: type: string email: type: string format: email pattern: >- ^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$ avatarUrl: type: - string - 'null' deactivatedAt: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' required: - userId - name - email - avatarUrl - deactivatedAt TeamBadgeDto: type: object properties: id: type: string name: type: string avatarUrl: type: - string - 'null' required: - id - name - avatarUrl LanguageDto: type: object properties: id: type: string minLength: 1 language: $ref: '#/components/schemas/CandidateLanguage' fluency: $ref: '#/components/schemas/CandidateFluency' required: - language CompensationDto: type: object properties: id: type: string minLength: 1 currency: $ref: '#/components/schemas/CandidateCurrency' totalCompensation: type: - number - 'null' baseCompensation: type: - number - 'null' required: - currency NextTaskDueDto: type: object properties: id: type: string minLength: 1 content: type: string dueDate: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' required: - id - content - dueDate WorkExperienceBadgeDto: type: object properties: title: type: - string - 'null' company: anyOf: - $ref: '#/components/schemas/CompanyBadgeDto' - type: 'null' required: - title - company CustomAttributeItemDto: type: object properties: attributeDefinitionId: type: string minLength: 1 label: type: string aiFillOngoing: type: boolean aiOverridden: type: boolean isFilledByAI: type: boolean value: $ref: '#/components/schemas/SharedCustomAttributeTypeDto' required: - attributeDefinitionId - label - aiFillOngoing - aiOverridden - isFilledByAI - value SkillBadgeDto: type: object properties: id: type: string name: type: string required: - id - name CandidateCustomAttributePathDto: type: string pattern: ^candidate\.custom\.[^\r\n]+$ DmCurrency: type: string enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BRL - BSD - BTC - BTN - BWP - BYN - BZD - CAD - CDF - CHF - CLF - CLP - CNH - CNY - COP - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GGP - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - IMP - INR - IQD - IRR - ISK - JEP - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRU - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLE - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - UYU - UZS - VEF - VES - VND - VUV - WST - XAF - XAG - XAU - XCD - XCG - XDR - XOF - XPD - XPF - XPT - YER - ZAR - ZMW - ZWG - ZWL CountryCode: type: string enum: - AF - AX - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - KH - CM - CA - CV - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CW - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MK - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - SS - ES - LK - SD - SR - SJ - SZ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - US - UM - UY - UZ - VU - VE - VN - VG - VI - WF - EH - XK - YE - ZM - ZW LocationType: type: string enum: - primary_home - secondary_home - primary_work - headquarters - regional_office CandidateLanguage: type: string enum: - Afrikaans - Albanian - Amharic - Arabic - Armenian - Assamese - Aymara - Azerbaijani - Bangla - Basque - Belarusian - Bemba - Berber - Bislama - Bosnian - Bulgarian - Burman - Catalan - Chechen - Chewa - Chinese (Mandarin) - Chinese (Cantonese) - Chittagonian - Croatian - Czech - Danish - Dari - Dhivehi - Dutch - Dzongkha - English - Estonian - Ewe - Fijian - Filipino - Finnish - French - Galician - Georgian - German - Greek - Guarani - Gujarati - Haitian Creole - Hausa - Hebrew - Hindi - Hungarian - Icelandic - Igbo - Indonesian - Irish - Italian - Japanese - Kannada - Kazakh - Khmer - Kinyarwanda - Kirundi - Korean - Kurdish - Kyrgyz - Lao - Latvian - Lingala - Lithuanian - Luganda - Luxembourgish - Macedonian - Malagasy - Malay - Malayalam - Maltese - Maori - Marathi - Moldovan - Mongolian - Montenegrin - Ndebele - Nepali - Norwegian - Odia - Oromo - Pashto - Persian - Polish - Portuguese - Punjabi - Quechua - Romanian - Russian - Samoan - Sango - Serbian - Sesotho - Setswana - Shona - Sindhi - Sinhala - Slovak - Slovenian - Somali - Spanish - Swahili - Swedish - Tajik - Tamil - Telugu - Tetum - Thai - Tigrinya - Tok Pisin - Tongan - Tsonga - Tswana - Turkish - Turkmen - Ukrainian - Urdu - Uzbek - Venda - Vietnamese - Welsh - Xhosa - Yoruba - Zulu CandidateFluency: anyOf: - type: string enum: - Elementary proficiency - Limited working proficiency - Professional working proficiency - Full professional proficiency - Native or bilingual proficiency - type: 'null' CandidateCurrency: $ref: '#/components/schemas/DmCurrency' CompanyBadgeDto: type: object properties: id: type: string name: type: string logoUrl: type: - string - 'null' required: - id - name - logoUrl SharedCustomAttributeTypeDto: oneOf: - $ref: '#/components/schemas/CustomTextTypeDto' - $ref: '#/components/schemas/CustomNumberTypeDto' - $ref: '#/components/schemas/CustomCheckboxTypeDto' - $ref: '#/components/schemas/CustomDateTypeDto' - $ref: '#/components/schemas/CustomTimestampTypeDto' - $ref: '#/components/schemas/CustomRatingTypeDto' - $ref: '#/components/schemas/CustomSelectTypeDto' - $ref: '#/components/schemas/CustomMultiSelectTypeDto' - $ref: '#/components/schemas/CustomCurrencyTypeDto' - $ref: '#/components/schemas/CustomDateRangeTypeDto' - $ref: '#/components/schemas/CustomDurationTypeDto' - $ref: '#/components/schemas/CustomUrlTypeDto' - $ref: '#/components/schemas/CustomEntityTypeDto' - $ref: '#/components/schemas/CustomMultiEntityTypeDto' CustomTextTypeDto: type: object properties: viewType: type: string enum: - customText text: type: - string - 'null' required: - viewType - text CustomNumberTypeDto: type: object properties: viewType: type: string enum: - customNumber number: type: - number - 'null' required: - viewType - number CustomCheckboxTypeDto: type: object properties: viewType: type: string enum: - customCheckbox checked: type: - boolean - 'null' required: - viewType - checked CustomDateTypeDto: type: object properties: viewType: type: string enum: - customDate date: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' required: - viewType - date CustomTimestampTypeDto: type: object properties: viewType: type: string enum: - customTimestamp timestamp: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' required: - viewType - timestamp CustomRatingTypeDto: type: object properties: viewType: type: string enum: - customRating rating: type: - number - 'null' required: - viewType - rating CustomSelectTypeDto: type: object properties: viewType: type: string enum: - customSelect select: type: - string - 'null' required: - viewType - select CustomMultiSelectTypeDto: type: object properties: viewType: type: string enum: - customMultiSelect multiSelect: type: array items: type: string required: - viewType - multiSelect CustomCurrencyTypeDto: type: object properties: viewType: type: string enum: - customCurrency monetaryAmount: anyOf: - $ref: '#/components/schemas/MonetaryAmountDto' - type: 'null' required: - viewType - monetaryAmount CustomDateRangeTypeDto: type: object properties: viewType: type: string enum: - customDateRange dateRange: anyOf: - $ref: '#/components/schemas/DateRangeDto' - type: 'null' required: - viewType - dateRange CustomDurationTypeDto: type: object properties: viewType: type: string enum: - customDuration duration: type: - number - 'null' required: - viewType - duration CustomUrlTypeDto: type: object properties: viewType: type: string enum: - customUrl url: type: - string - 'null' required: - viewType - url CustomEntityTypeDto: type: object properties: viewType: type: string enum: - customEntity type: type: string enum: - user id: type: - string - 'null' entity: anyOf: - $ref: '#/components/schemas/UserBadgeDto' - type: 'null' required: - viewType - type - id CustomMultiEntityTypeDto: type: object properties: viewType: type: string enum: - customMultiEntity type: type: string enum: - user ids: type: array items: type: string entities: type: array items: $ref: '#/components/schemas/UserBadgeDto' required: - viewType - type - ids MonetaryAmountDto: type: object properties: currency: $ref: '#/components/schemas/DmCurrency' amount: type: number required: - currency - amount DateRangeDto: type: object properties: startDate: $ref: '#/components/schemas/DateISO' endDate: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' required: - startDate - endDate UserBadgeDto: type: object properties: id: type: string name: type: string avatarUrl: type: - string - 'null' deactivatedAt: anyOf: - $ref: '#/components/schemas/DateISO' - type: 'null' required: - id - name - avatarUrl - deactivatedAt headers: RateLimit: description: >- Quota state for this endpoint, as an RFC 8941 structured field (draft-ietf-httpapi-ratelimit-headers). The quoted value names the policy — the operationId of the endpoint the counters belong to. `r` is how many requests are left in the current window, `t` how many seconds remain before it resets. schema: type: string example: '"getCandidates";r=417;t=23' RateLimit-Policy: description: >- The policy the RateLimit header reports against, as an RFC 8941 structured field. `q` is the quota — the requests allowed per window — and `w` the window length in seconds. Limits are per endpoint, so the quota differs between operations. This is the quota in force for the calling workspace, which can be lower or higher than the default published on the operation; treat it as authoritative. schema: type: string example: '"getCandidates";q=600;w=60' Retry-After: description: >- Seconds to wait before retrying. Sent on 429 responses; it matches the `t` parameter of the RateLimit header. schema: type: integer example: 23 securitySchemes: x-api-key: type: apiKey name: x-api-key in: header description: >- API key for authentication. Get your API key from Settings → API Keys in your Spott dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.