Get candidates with cursor-based pagination
Copy
Ask AI
curl --request GET \
--url https://api.gospott.com/candidates \
--header 'x-api-key: <api-key>'Copy
Ask AI
{
"items": [
{
"id": "<string>",
"name": {
"viewType": "candidateName",
"avatarUrl": "<string>",
"firstName": "<string>",
"lastName": "<string>"
},
"gender": {
"viewType": "candidateGender",
"gender": "male"
},
"nationality": {
"viewType": "candidateNationality",
"nationality": [
"Afghan"
]
},
"status": {
"viewType": "candidateStatus",
"status": [
"actively_looking"
]
},
"emails": {
"viewType": "candidateEmails",
"emails": [
{
"purpose": "personal",
"email": "[email protected]",
"isPrimary": true
}
]
},
"phoneNumbers": {
"viewType": "candidatePhoneNumbers",
"phoneNumbers": [
{
"purpose": "personal",
"phoneNumber": "<string>",
"isPrimary": true
}
]
},
"locations": {
"viewType": "candidateLocation",
"locations": [
{
"type": "primary_home",
"street1": "<string>",
"street2": "<string>",
"postalCode": "<string>",
"city": "<string>",
"region": "<string>",
"state": "<string>",
"country": "<string>",
"rawCityCountry": "<string>",
"latitude": 123,
"longitude": 123,
"formattedAddress": "<string>"
}
]
},
"dateOfBirth": {
"viewType": "candidateDateOfBirth",
"dateOfBirth": "2023-11-07T05:31:56Z"
},
"socialMedia": {
"viewType": "candidateSocialMedia",
"socialMedia": [
{
"url": "<string>",
"type": "LINKEDIN",
"isPrimary": true
}
]
},
"lastInteractionDate": {
"viewType": "candidateLastInteractionDate",
"lastInteractionDate": "2023-11-07T05:31:56Z"
},
"lastInteractionWith": {
"viewType": "candidateLastInteractionWith",
"user": {
"userId": "<string>",
"name": "<string>",
"email": "<string>",
"avatarUrl": "<string>",
"deactivatedAt": "2023-11-07T05:31:56Z"
}
},
"nextInteractionDate": {
"viewType": "candidateNextInteractionDate",
"nextInteractionDate": "2023-11-07T05:31:56Z"
},
"nextInteractionWith": {
"viewType": "candidateNextInteractionWith",
"user": {
"userId": "<string>",
"name": "<string>",
"email": "<string>",
"avatarUrl": "<string>",
"deactivatedAt": "2023-11-07T05:31:56Z"
}
},
"mainContact": {
"viewType": "candidateMainContact",
"user": {
"userId": "<string>",
"name": "<string>",
"email": "<string>",
"avatarUrl": "<string>",
"deactivatedAt": "2023-11-07T05:31:56Z"
}
},
"languages": {
"viewType": "candidateLanguages",
"languages": [
{
"language": "English",
"id": "clxkq1qyr0000t7t6h1g1g1g1",
"fluency": "Native or bilingual proficiency"
}
]
},
"compensation": {
"viewType": "candidateCompensation",
"compensation": {
"currency": "USD",
"id": "<string>",
"totalCompensation": 100000,
"baseCompensation": 80000
}
},
"currentPlacements": {
"viewType": "candidateCurrentPlacements",
"hasCurrentPlacement": true,
"placements": [
{
"id": "<string>",
"company": {
"id": "<string>",
"name": "<string>",
"logoUrl": "<string>"
},
"startDate": "2023-11-07T05:31:56Z",
"endDate": "2023-11-07T05:31:56Z"
}
]
},
"nextTaskDue": {
"viewType": "candidateNextTaskDue",
"nextTaskDue": {
"id": "<string>",
"content": "<string>",
"dueDate": "2023-11-07T05:31:56Z"
}
},
"createdAt": "2023-11-07T05:31:56Z",
"modifiedAt": "2023-11-07T05:31:56Z",
"lastActivityDate": "2023-11-07T05:31:56Z",
"acquisitionSource": {
"viewType": "candidateAcquisitionSource",
"acquisitionSource": "manual"
},
"lastLinkedinDiffAt": "2023-11-07T05:31:56Z",
"isDiffingLinkedin": true,
"customAttributes": [
{
"value": {
"viewType": "customImage",
"imageUrl": "<string>"
},
"attributeDefinitionId": "<string>",
"label": "<string>",
"description": "<string>",
"filledByAI": true,
"options": [
"<string>"
]
}
],
"aiSummary": "<string>"
}
],
"pageInfo": {
"nextCursor": "<string>",
"hasNextPage": true
}
}Candidates
Get candidates with cursor-based pagination
Retrieve a list of candidates using efficient cursor-based pagination.
This endpoint returns candidates ordered by modification date (oldest first) and supports:
- Cursor-based pagination for efficient data streaming
- Filtering by modification date to fetch only updated candidates
- Configurable page size (1-50 items)
- Full candidate details including custom attributes
Use Cases:
- Initial data synchronization
- Incremental updates using modifiedSince
- Streaming large candidate datasets
- API integrations requiring candidate data
Pagination: The endpoint uses cursor-based pagination for optimal performance:
- First request: omit cursor parameter
- Check hasNextPage in response
- Subsequent requests: use nextCursor from previous response
- Continue until hasNextPage is false
Performance:
- Maximum 50 candidates per request
- Custom attributes fetched efficiently in bulk
- Optimized for large datasets
GET
/
candidates
Get candidates with cursor-based pagination
Copy
Ask AI
curl --request GET \
--url https://api.gospott.com/candidates \
--header 'x-api-key: <api-key>'Copy
Ask AI
{
"items": [
{
"id": "<string>",
"name": {
"viewType": "candidateName",
"avatarUrl": "<string>",
"firstName": "<string>",
"lastName": "<string>"
},
"gender": {
"viewType": "candidateGender",
"gender": "male"
},
"nationality": {
"viewType": "candidateNationality",
"nationality": [
"Afghan"
]
},
"status": {
"viewType": "candidateStatus",
"status": [
"actively_looking"
]
},
"emails": {
"viewType": "candidateEmails",
"emails": [
{
"purpose": "personal",
"email": "[email protected]",
"isPrimary": true
}
]
},
"phoneNumbers": {
"viewType": "candidatePhoneNumbers",
"phoneNumbers": [
{
"purpose": "personal",
"phoneNumber": "<string>",
"isPrimary": true
}
]
},
"locations": {
"viewType": "candidateLocation",
"locations": [
{
"type": "primary_home",
"street1": "<string>",
"street2": "<string>",
"postalCode": "<string>",
"city": "<string>",
"region": "<string>",
"state": "<string>",
"country": "<string>",
"rawCityCountry": "<string>",
"latitude": 123,
"longitude": 123,
"formattedAddress": "<string>"
}
]
},
"dateOfBirth": {
"viewType": "candidateDateOfBirth",
"dateOfBirth": "2023-11-07T05:31:56Z"
},
"socialMedia": {
"viewType": "candidateSocialMedia",
"socialMedia": [
{
"url": "<string>",
"type": "LINKEDIN",
"isPrimary": true
}
]
},
"lastInteractionDate": {
"viewType": "candidateLastInteractionDate",
"lastInteractionDate": "2023-11-07T05:31:56Z"
},
"lastInteractionWith": {
"viewType": "candidateLastInteractionWith",
"user": {
"userId": "<string>",
"name": "<string>",
"email": "<string>",
"avatarUrl": "<string>",
"deactivatedAt": "2023-11-07T05:31:56Z"
}
},
"nextInteractionDate": {
"viewType": "candidateNextInteractionDate",
"nextInteractionDate": "2023-11-07T05:31:56Z"
},
"nextInteractionWith": {
"viewType": "candidateNextInteractionWith",
"user": {
"userId": "<string>",
"name": "<string>",
"email": "<string>",
"avatarUrl": "<string>",
"deactivatedAt": "2023-11-07T05:31:56Z"
}
},
"mainContact": {
"viewType": "candidateMainContact",
"user": {
"userId": "<string>",
"name": "<string>",
"email": "<string>",
"avatarUrl": "<string>",
"deactivatedAt": "2023-11-07T05:31:56Z"
}
},
"languages": {
"viewType": "candidateLanguages",
"languages": [
{
"language": "English",
"id": "clxkq1qyr0000t7t6h1g1g1g1",
"fluency": "Native or bilingual proficiency"
}
]
},
"compensation": {
"viewType": "candidateCompensation",
"compensation": {
"currency": "USD",
"id": "<string>",
"totalCompensation": 100000,
"baseCompensation": 80000
}
},
"currentPlacements": {
"viewType": "candidateCurrentPlacements",
"hasCurrentPlacement": true,
"placements": [
{
"id": "<string>",
"company": {
"id": "<string>",
"name": "<string>",
"logoUrl": "<string>"
},
"startDate": "2023-11-07T05:31:56Z",
"endDate": "2023-11-07T05:31:56Z"
}
]
},
"nextTaskDue": {
"viewType": "candidateNextTaskDue",
"nextTaskDue": {
"id": "<string>",
"content": "<string>",
"dueDate": "2023-11-07T05:31:56Z"
}
},
"createdAt": "2023-11-07T05:31:56Z",
"modifiedAt": "2023-11-07T05:31:56Z",
"lastActivityDate": "2023-11-07T05:31:56Z",
"acquisitionSource": {
"viewType": "candidateAcquisitionSource",
"acquisitionSource": "manual"
},
"lastLinkedinDiffAt": "2023-11-07T05:31:56Z",
"isDiffingLinkedin": true,
"customAttributes": [
{
"value": {
"viewType": "customImage",
"imageUrl": "<string>"
},
"attributeDefinitionId": "<string>",
"label": "<string>",
"description": "<string>",
"filledByAI": true,
"options": [
"<string>"
]
}
],
"aiSummary": "<string>"
}
],
"pageInfo": {
"nextCursor": "<string>",
"hasNextPage": true
}
}Authorizations
API key for authentication. Get your API key from Settings → API Keys in your Spott dashboard.
Query Parameters
Number of candidates to return per page (min: 1, max: 50, default: 25)
Required range:
1 <= x <= 50Filter candidates modified on or after this date. Useful for incremental synchronization. Defaults to beginning of time if not provided.
Example:
"2024-11-01T00:00:00.000Z"
Base64-encoded cursor for pagination. Use the nextCursor value from a previous response to fetch the next page. Omit for the first page.
Example:
"eyJtb2RpZmllZEF0IjoiMjAyNC0xMS0wNlQxMDozMDowMC4wMDBaIiwiaWQiOiJjYW5kaWRhdGUtMTIzIn0="
Response
Candidates retrieved successfully
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Available options:
candidateNationality Available options:
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, 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, Tuvaluan, Ugandan, Ukrainian, Uruguayan, Uzbekistani, Venezuelan, Vietnamese, Welsh, Yemenite, Zambian, Zimbabwean Show child attributes
Show child attributes
Available options:
candidateEmails Show child attributes
Show child attributes
Available options:
candidatePhoneNumbers Show child attributes
Show child attributes
Available options:
candidateLocation Show child attributes
Show child attributes
Available options:
primary_home, secondary_home, primary_work, headquarters, regional_office Show child attributes
Show child attributes
Available options:
candidateSocialMedia Show child attributes
Show child attributes
Available options:
candidateLastInteractionWith Show child attributes
Show child attributes
Show child attributes
Show child attributes
Available options:
candidateNextInteractionWith Show child attributes
Show child attributes
Show child attributes
Show child attributes
Available options:
candidateMainContact Show child attributes
Show child attributes
Available options:
candidateLanguages Show child attributes
Show child attributes
The spoken or written language
Available options:
Afrikaans, Albanian, Amharic, Arabic, Armenian, Assamese, Aymara, Azerbaijani, Bangla, Basque, Belarusian, Bemba, Berber, Bislama, Bosnian, Bulgarian, Burman, Catalan, 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 Example:
"English"
The unique identifier for the language record (optional for create/update)
Example:
"clxkq1qyr0000t7t6h1g1g1g1"
The fluency level in the specified language
Available options:
Elementary proficiency, Limited working proficiency, Professional working proficiency, Full professional proficiency, Native or bilingual proficiency Example:
"Native or bilingual proficiency"
Show child attributes
Show child attributes
Available options:
candidateCompensation Show child attributes
Show child attributes
The currency code (ISO 4217)
Available options:
USD, EUR, GBP, JPY, CNY, INR, SAR, AED, NOK, SEK, DKK, MXN, BRL, ARS, AUD, CAD, NZD, EGP, CHF, SGD, HKD, KRW, TWD, THB, VND, IDR, ILS, TRY, ZAR, RUB, PLN, HUF, RON, BGN, CZK Example:
"USD"
The unique identifier for the compensation record (optional for create/update)
The total compensation amount (optional)
Example:
100000
The base compensation amount (optional)
Example:
80000
Show child attributes
Show child attributes
Available options:
candidateCurrentPlacements Show child attributes
Show child attributes
Show child attributes
Show child attributes
Available options:
candidateNextTaskDue Show child attributes
Show child attributes
Available options:
candidateAcquisitionSource Available options:
manual, cv_parse, inbound_vacancy_portal, chrome_extension_linkedin, inbound_from_linkedin_jobboard_email, inbound_from_external_jobboard, juicebox Show child attributes
Show child attributes
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
- Option 11
- Option 12
- Option 13
⌘I