Skip to main content
PATCH
/
candidates
/
{id}
Update candidate
curl --request PATCH \
  --url https://api.gospott.com/candidates/{id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "firstName": "John",
  "middleName": "William",
  "lastName": "Doe",
  "secondLastName": "Garcia",
  "compensation": {
    "currency": "USD",
    "id": "<string>",
    "totalCompensation": 100000,
    "baseCompensation": 80000
  },
  "mainContact": {
    "userId": "<string>"
  },
  "languages": [
    {
      "language": "English",
      "id": "clxkq1qyr0000t7t6h1g1g1g1",
      "fluency": "Native or bilingual proficiency"
    }
  ],
  "gender": "male",
  "nationality": [
    "Afghan"
  ],
  "status": [
    "actively_looking"
  ],
  "acquisitionSource": "manual",
  "locations": [
    {
      "type": "primary_home",
      "street1": "<string>",
      "street2": "<string>",
      "postalCode": "<string>",
      "city": "<string>",
      "region": "<string>",
      "state": "<string>",
      "country": "<string>",
      "latitude": 123,
      "longitude": 123
    }
  ],
  "socialMedia": [
    {
      "url": "<string>",
      "type": "LINKEDIN",
      "isPrimary": true
    }
  ],
  "emails": [
    {
      "purpose": "personal",
      "email": "jsmith@example.com",
      "isPrimary": true
    }
  ],
  "phoneNumbers": [
    {
      "purpose": "personal",
      "phoneNumber": "<string>",
      "isPrimary": true
    }
  ],
  "visibleIfClientContact": true,
  "dateOfBirth": "1990-05-15T00:00:00.000Z",
  "lastInteractionAt": "2024-01-15T14:30:00.000Z",
  "lastInteractionWithId": "user-uuid-here"
}
'
{
  "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": "jsmith@example.com",
        "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"
  },
  "latestWorkExperience": {
    "title": "<string>",
    "company": {
      "id": "<string>",
      "name": "<string>",
      "logoUrl": "<string>"
    }
  },
  "lastLinkedinDiffAt": "2023-11-07T05:31:56Z",
  "isDiffingLinkedin": true,
  "customAttributes": [
    {
      "value": {
        "viewType": "customText",
        "text": "Senior Software Engineer"
      },
      "attributeDefinitionId": "<string>",
      "label": "<string>",
      "aiFillOngoing": true,
      "aiOverridden": true,
      "isFilledByAI": true,
      "options": [
        "<string>"
      ]
    }
  ],
  "aiSummary": "<string>",
  "clientContacts": {
    "viewType": "candidateClientContacts",
    "clientContacts": [
      {
        "id": "<string>",
        "company": {
          "id": "<string>",
          "name": "<string>",
          "logoUrl": "<string>"
        },
        "role": "<string>",
        "department": "<string>",
        "startDate": "2023-11-07T05:31:56Z",
        "endDate": "2023-11-07T05:31:56Z",
        "active": true,
        "emailAddresses": [
          {
            "purpose": "personal",
            "email": "jsmith@example.com",
            "isPrimary": true
          }
        ],
        "phoneNumbers": [
          {
            "purpose": "personal",
            "phoneNumber": "<string>",
            "isPrimary": true
          }
        ],
        "stage": {
          "id": "<string>",
          "order": 123,
          "name": "<string>",
          "colorHex": "<string>"
        },
        "customAttributes": [
          {
            "value": {
              "viewType": "customText",
              "text": "Senior Software Engineer"
            },
            "attributeDefinitionId": "<string>",
            "label": "<string>",
            "aiFillOngoing": true,
            "aiOverridden": true,
            "isFilledByAI": true,
            "options": [
              "<string>"
            ]
          }
        ]
      }
    ]
  },
  "isVisibleIfClientContact": true,
  "hasClientContacts": true,
  "hasActiveClientContacts": true,
  "lastAgentChatId": "<string>",
  "cvAttachmentId": "<string>",
  "linkedInProfile": {
    "viewType": "candidateLinkedInProfile",
    "headline": "<string>",
    "about": "<string>",
    "skills": [
      "<string>"
    ]
  }
}

Authorizations

​
x-api-key
string
header
required

API key for authentication. Get your API key from Settings → API Keys in your Spott dashboard.

Path Parameters

​
id
string
required

Body

application/json
​
firstName
string

The first name of the candidate

Example:

"John"

​
middleName
string

The middle name of the candidate

Example:

"William"

​
lastName
string

The last name of the candidate

Example:

"Doe"

​
secondLastName
string

The second last name of the candidate (common in Spanish-speaking countries)

Example:

"Garcia"

​
compensation
object

Compensation expectations for the candidate

​
mainContact
object

The main contact (recruiter) assigned to this candidate

​
languages
object[]

Languages spoken by the candidate

​
gender
enum<string> | null

The gender of the candidate

Available options:
male,
female,
x
​
nationality
enum<string>[]

The nationalities of the candidate

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
​
status
enum<string>[]

The current status(es) of the candidate in the recruitment process

Available options:
actively_looking,
approachable_but_not_actively_looking,
do_not_contact,
do_not_poach,
not_actively_looking
​
acquisitionSource
enum<string>

How the candidate was acquired (e.g., referral, job board, LinkedIn)

Available options:
manual,
cv_parse,
inbound_vacancy_portal,
inbound_spontaneous_application,
chrome_extension_linkedin,
inbound_from_linkedin_jobboard_email,
inbound_from_external_jobboard,
juicebox,
maildrop,
csv_import
​
locations
object[]

Physical locations associated with the candidate

​
socialMedia
object[]

Social media profiles of the candidate (e.g., LinkedIn URL)

​
emails
object[]

Email addresses of the candidate

​
phoneNumbers
object[]

Phone numbers of the candidate

​
visibleIfClientContact
boolean | null

Whether this candidate should be visible when they are also a client contact

​
dateOfBirth
string<date-time> | null

The date of birth of the candidate

Example:

"1990-05-15T00:00:00.000Z"

​
lastInteractionAt
string<date-time> | null

The date and time of the last interaction with the candidate

Example:

"2024-01-15T14:30:00.000Z"

​
lastInteractionWithId
string | null

The user ID of the person who last interacted with the candidate

Example:

"user-uuid-here"

Response

Candidate updated successfully

​
id
string
required
​
name
object
required
​
gender
object
required
​
nationality
object
required
​
status
object
required
​
emails
object
required
​
phoneNumbers
object
required
​
locations
object
required
​
dateOfBirth
object
required
​
socialMedia
object
required
​
lastInteractionDate
object
required
​
lastInteractionWith
object
required
​
nextInteractionDate
object
required
​
nextInteractionWith
object
required
​
mainContact
object
required
​
languages
object
required
​
compensation
object
required
​
currentPlacements
object
required
​
nextTaskDue
object
required
​
createdAt
string<date-time>
required
​
modifiedAt
string<date-time>
required
​
lastActivityDate
string<date-time>
required
​
acquisitionSource
object
required
​
latestWorkExperience
object
required
​
lastLinkedinDiffAt
string<date-time> | null
required
​
isDiffingLinkedin
boolean
required
​
customAttributes
object[]
required
​
aiSummary
string | null
required
​
clientContacts
object
required
​
isVisibleIfClientContact
boolean | null
required
​
hasClientContacts
boolean | null
required
​
hasActiveClientContacts
boolean | null
required
​
lastAgentChatId
string | null
required
​
cvAttachmentId
string | null
required
​
linkedInProfile
object
required