Skip to main content
POST
/
external
/
v1
/
create_or_update_candidate
Create or Update Candidate
curl --request POST \
  --url https://api.example.com/external/v1/create_or_update_candidate

​
Create or Update Candidate

Create a new candidate profile or update an existing one. The candidate is identified by email address — if a candidate with the given email exists, their data is updated.

​
Endpoint

POST /external/v1/create_or_update_candidate

​
Request Body

FieldTypeRequiredDescription
emailstringYesCandidate’s email address (used as identifier)
first_namestringYesCandidate’s first name
last_namestringYesCandidate’s last name
phonestringNoCandidate’s phone number
custom_fieldsobjectNoAdditional candidate data

​
Example Request

curl -X POST "https://your-instance.firstwork.com/external/v1/create_or_update_candidate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.smith@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "phone": "+1987654321",
    "custom_fields": {
      "source": "referral",
      "department": "Engineering"
    }
  }'

​
Example Response

{
  "status": "success",
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "email": "jane.smith@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "phone": "+1987654321",
    "created": false,
    "updated": true
  }
}

​
Notes

  • If the email exists, the candidate is updated (returns "created": false, "updated": true)
  • If the email is new, a candidate is created (returns "created": true, "updated": false)
  • Phone number format should include country code