Create person
curl --request POST \
--url https://api.stardex.ai/v1/persons \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"linkedin_url": "https://www.linkedin.com/in/johndoe",
"current_job_title": "Software Engineer",
"location": "San Francisco, CA",
"company_name": "Tech Corp",
"emails": [
"john.doe@example.com"
],
"work_email": "john@techcorp.com",
"work_phone": "+1-555-0100",
"personal_email": "john.doe@gmail.com",
"mobile_phone": "+1-555-0123",
"phone_numbers": [
"+1-555-0199"
],
"notes": "Strong backend experience, open to relocation.",
"job_id": "345e6789-e01b-23c4-d567-890123456789",
"external_source_id": "ext-candidate-12345",
"enrich_record": true,
"person_owner": "234e5678-e90a-12b3-c456-789012345678",
"sourced_by": "234e5678-e90a-12b3-c456-789012345678",
"custom_fields": [
{
"attribute_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"value": "Senior"
},
{
"attribute_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"value": 8
},
{
"attribute_id": "c3d4e5f6-a7b8-9012-cdef-234567890123",
"add_company_ids": [
"456e7890-e12b-34d5-a678-901234567890"
]
}
]
}
'import requests
url = "https://api.stardex.ai/v1/persons"
payload = {
"name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"linkedin_url": "https://www.linkedin.com/in/johndoe",
"current_job_title": "Software Engineer",
"location": "San Francisco, CA",
"company_name": "Tech Corp",
"emails": ["john.doe@example.com"],
"work_email": "john@techcorp.com",
"work_phone": "+1-555-0100",
"personal_email": "john.doe@gmail.com",
"mobile_phone": "+1-555-0123",
"phone_numbers": ["+1-555-0199"],
"notes": "Strong backend experience, open to relocation.",
"job_id": "345e6789-e01b-23c4-d567-890123456789",
"external_source_id": "ext-candidate-12345",
"enrich_record": True,
"person_owner": "234e5678-e90a-12b3-c456-789012345678",
"sourced_by": "234e5678-e90a-12b3-c456-789012345678",
"custom_fields": [
{
"attribute_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"value": "Senior"
},
{
"attribute_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"value": 8
},
{
"attribute_id": "c3d4e5f6-a7b8-9012-cdef-234567890123",
"add_company_ids": ["456e7890-e12b-34d5-a678-901234567890"]
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'John Doe',
first_name: 'John',
last_name: 'Doe',
linkedin_url: 'https://www.linkedin.com/in/johndoe',
current_job_title: 'Software Engineer',
location: 'San Francisco, CA',
company_name: 'Tech Corp',
emails: ['john.doe@example.com'],
work_email: 'john@techcorp.com',
work_phone: '+1-555-0100',
personal_email: 'john.doe@gmail.com',
mobile_phone: '+1-555-0123',
phone_numbers: ['+1-555-0199'],
notes: 'Strong backend experience, open to relocation.',
job_id: '345e6789-e01b-23c4-d567-890123456789',
external_source_id: 'ext-candidate-12345',
enrich_record: true,
person_owner: '234e5678-e90a-12b3-c456-789012345678',
sourced_by: '234e5678-e90a-12b3-c456-789012345678',
custom_fields: [
{attribute_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890', value: 'Senior'},
{attribute_id: 'b2c3d4e5-f6a7-8901-bcde-f12345678901', value: 8},
{
attribute_id: 'c3d4e5f6-a7b8-9012-cdef-234567890123',
add_company_ids: ['456e7890-e12b-34d5-a678-901234567890']
}
]
})
};
fetch('https://api.stardex.ai/v1/persons', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.stardex.ai/v1/persons",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'John Doe',
'first_name' => 'John',
'last_name' => 'Doe',
'linkedin_url' => 'https://www.linkedin.com/in/johndoe',
'current_job_title' => 'Software Engineer',
'location' => 'San Francisco, CA',
'company_name' => 'Tech Corp',
'emails' => [
'john.doe@example.com'
],
'work_email' => 'john@techcorp.com',
'work_phone' => '+1-555-0100',
'personal_email' => 'john.doe@gmail.com',
'mobile_phone' => '+1-555-0123',
'phone_numbers' => [
'+1-555-0199'
],
'notes' => 'Strong backend experience, open to relocation.',
'job_id' => '345e6789-e01b-23c4-d567-890123456789',
'external_source_id' => 'ext-candidate-12345',
'enrich_record' => true,
'person_owner' => '234e5678-e90a-12b3-c456-789012345678',
'sourced_by' => '234e5678-e90a-12b3-c456-789012345678',
'custom_fields' => [
[
'attribute_id' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
'value' => 'Senior'
],
[
'attribute_id' => 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
'value' => 8
],
[
'attribute_id' => 'c3d4e5f6-a7b8-9012-cdef-234567890123',
'add_company_ids' => [
'456e7890-e12b-34d5-a678-901234567890'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.stardex.ai/v1/persons"
payload := strings.NewReader("{\n \"name\": \"John Doe\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"linkedin_url\": \"https://www.linkedin.com/in/johndoe\",\n \"current_job_title\": \"Software Engineer\",\n \"location\": \"San Francisco, CA\",\n \"company_name\": \"Tech Corp\",\n \"emails\": [\n \"john.doe@example.com\"\n ],\n \"work_email\": \"john@techcorp.com\",\n \"work_phone\": \"+1-555-0100\",\n \"personal_email\": \"john.doe@gmail.com\",\n \"mobile_phone\": \"+1-555-0123\",\n \"phone_numbers\": [\n \"+1-555-0199\"\n ],\n \"notes\": \"Strong backend experience, open to relocation.\",\n \"job_id\": \"345e6789-e01b-23c4-d567-890123456789\",\n \"external_source_id\": \"ext-candidate-12345\",\n \"enrich_record\": true,\n \"person_owner\": \"234e5678-e90a-12b3-c456-789012345678\",\n \"sourced_by\": \"234e5678-e90a-12b3-c456-789012345678\",\n \"custom_fields\": [\n {\n \"attribute_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"value\": \"Senior\"\n },\n {\n \"attribute_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n \"value\": 8\n },\n {\n \"attribute_id\": \"c3d4e5f6-a7b8-9012-cdef-234567890123\",\n \"add_company_ids\": [\n \"456e7890-e12b-34d5-a678-901234567890\"\n ]\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.stardex.ai/v1/persons")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"John Doe\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"linkedin_url\": \"https://www.linkedin.com/in/johndoe\",\n \"current_job_title\": \"Software Engineer\",\n \"location\": \"San Francisco, CA\",\n \"company_name\": \"Tech Corp\",\n \"emails\": [\n \"john.doe@example.com\"\n ],\n \"work_email\": \"john@techcorp.com\",\n \"work_phone\": \"+1-555-0100\",\n \"personal_email\": \"john.doe@gmail.com\",\n \"mobile_phone\": \"+1-555-0123\",\n \"phone_numbers\": [\n \"+1-555-0199\"\n ],\n \"notes\": \"Strong backend experience, open to relocation.\",\n \"job_id\": \"345e6789-e01b-23c4-d567-890123456789\",\n \"external_source_id\": \"ext-candidate-12345\",\n \"enrich_record\": true,\n \"person_owner\": \"234e5678-e90a-12b3-c456-789012345678\",\n \"sourced_by\": \"234e5678-e90a-12b3-c456-789012345678\",\n \"custom_fields\": [\n {\n \"attribute_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"value\": \"Senior\"\n },\n {\n \"attribute_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n \"value\": 8\n },\n {\n \"attribute_id\": \"c3d4e5f6-a7b8-9012-cdef-234567890123\",\n \"add_company_ids\": [\n \"456e7890-e12b-34d5-a678-901234567890\"\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.stardex.ai/v1/persons")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"John Doe\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"linkedin_url\": \"https://www.linkedin.com/in/johndoe\",\n \"current_job_title\": \"Software Engineer\",\n \"location\": \"San Francisco, CA\",\n \"company_name\": \"Tech Corp\",\n \"emails\": [\n \"john.doe@example.com\"\n ],\n \"work_email\": \"john@techcorp.com\",\n \"work_phone\": \"+1-555-0100\",\n \"personal_email\": \"john.doe@gmail.com\",\n \"mobile_phone\": \"+1-555-0123\",\n \"phone_numbers\": [\n \"+1-555-0199\"\n ],\n \"notes\": \"Strong backend experience, open to relocation.\",\n \"job_id\": \"345e6789-e01b-23c4-d567-890123456789\",\n \"external_source_id\": \"ext-candidate-12345\",\n \"enrich_record\": true,\n \"person_owner\": \"234e5678-e90a-12b3-c456-789012345678\",\n \"sourced_by\": \"234e5678-e90a-12b3-c456-789012345678\",\n \"custom_fields\": [\n {\n \"attribute_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"value\": \"Senior\"\n },\n {\n \"attribute_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n \"value\": 8\n },\n {\n \"attribute_id\": \"c3d4e5f6-a7b8-9012-cdef-234567890123\",\n \"add_company_ids\": [\n \"456e7890-e12b-34d5-a678-901234567890\"\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "John Doe",
"linkedin_public_id": "johndoe",
"current_job_title": "Software Engineer",
"company_name": "Tech Corp",
"location": "San Francisco, CA",
"emails": [
{
"contact_data_type": "work",
"value": "john@techcorp.com"
}
],
"phones": [
{
"contact_data_type": "mobile",
"value": "+1-555-0123"
}
],
"candidate_id": "789e0123-e45f-67a8-b901-234567890123",
"client_contact_id": null,
"external_source_id": null
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "PERSON_DELETION_REQUESTED",
"message": "This person asked to be removed from your workspace and can't be added again."
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}Persons
Create person
Create a new person record with contact details and optional job association. Returns the created person with IDs for further operations. Pass custom_fields to set custom field values in the same call, and sourced_by with job_id to record which team member sourced the candidate.
Warning: linkedin_url is optional but strongly recommended. It is the only reliable deduplication key for this endpoint. When provided, an existing person with that LinkedIn profile is matched and updated (never duplicated).
Automatic merge: when the new person has the same name as exactly one existing person, and also shares their email and phone number (or shares one of them, and their work histories, current company included, have a company in common or one of them has no work history), the new record is merged into the existing one. A new person whose external_source_id differs from the existing person’s is never merged. The response then describes the existing person, including its id. Merges are listed under Settings → Audit Log → Merged Records. If none of these conditions hold, a new person is created, so prefer PATCH /v1/persons/{id} when you already have the person ID.
POST
/
v1
/
persons
Create person
curl --request POST \
--url https://api.stardex.ai/v1/persons \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"linkedin_url": "https://www.linkedin.com/in/johndoe",
"current_job_title": "Software Engineer",
"location": "San Francisco, CA",
"company_name": "Tech Corp",
"emails": [
"john.doe@example.com"
],
"work_email": "john@techcorp.com",
"work_phone": "+1-555-0100",
"personal_email": "john.doe@gmail.com",
"mobile_phone": "+1-555-0123",
"phone_numbers": [
"+1-555-0199"
],
"notes": "Strong backend experience, open to relocation.",
"job_id": "345e6789-e01b-23c4-d567-890123456789",
"external_source_id": "ext-candidate-12345",
"enrich_record": true,
"person_owner": "234e5678-e90a-12b3-c456-789012345678",
"sourced_by": "234e5678-e90a-12b3-c456-789012345678",
"custom_fields": [
{
"attribute_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"value": "Senior"
},
{
"attribute_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"value": 8
},
{
"attribute_id": "c3d4e5f6-a7b8-9012-cdef-234567890123",
"add_company_ids": [
"456e7890-e12b-34d5-a678-901234567890"
]
}
]
}
'import requests
url = "https://api.stardex.ai/v1/persons"
payload = {
"name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"linkedin_url": "https://www.linkedin.com/in/johndoe",
"current_job_title": "Software Engineer",
"location": "San Francisco, CA",
"company_name": "Tech Corp",
"emails": ["john.doe@example.com"],
"work_email": "john@techcorp.com",
"work_phone": "+1-555-0100",
"personal_email": "john.doe@gmail.com",
"mobile_phone": "+1-555-0123",
"phone_numbers": ["+1-555-0199"],
"notes": "Strong backend experience, open to relocation.",
"job_id": "345e6789-e01b-23c4-d567-890123456789",
"external_source_id": "ext-candidate-12345",
"enrich_record": True,
"person_owner": "234e5678-e90a-12b3-c456-789012345678",
"sourced_by": "234e5678-e90a-12b3-c456-789012345678",
"custom_fields": [
{
"attribute_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"value": "Senior"
},
{
"attribute_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"value": 8
},
{
"attribute_id": "c3d4e5f6-a7b8-9012-cdef-234567890123",
"add_company_ids": ["456e7890-e12b-34d5-a678-901234567890"]
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'John Doe',
first_name: 'John',
last_name: 'Doe',
linkedin_url: 'https://www.linkedin.com/in/johndoe',
current_job_title: 'Software Engineer',
location: 'San Francisco, CA',
company_name: 'Tech Corp',
emails: ['john.doe@example.com'],
work_email: 'john@techcorp.com',
work_phone: '+1-555-0100',
personal_email: 'john.doe@gmail.com',
mobile_phone: '+1-555-0123',
phone_numbers: ['+1-555-0199'],
notes: 'Strong backend experience, open to relocation.',
job_id: '345e6789-e01b-23c4-d567-890123456789',
external_source_id: 'ext-candidate-12345',
enrich_record: true,
person_owner: '234e5678-e90a-12b3-c456-789012345678',
sourced_by: '234e5678-e90a-12b3-c456-789012345678',
custom_fields: [
{attribute_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890', value: 'Senior'},
{attribute_id: 'b2c3d4e5-f6a7-8901-bcde-f12345678901', value: 8},
{
attribute_id: 'c3d4e5f6-a7b8-9012-cdef-234567890123',
add_company_ids: ['456e7890-e12b-34d5-a678-901234567890']
}
]
})
};
fetch('https://api.stardex.ai/v1/persons', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.stardex.ai/v1/persons",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'John Doe',
'first_name' => 'John',
'last_name' => 'Doe',
'linkedin_url' => 'https://www.linkedin.com/in/johndoe',
'current_job_title' => 'Software Engineer',
'location' => 'San Francisco, CA',
'company_name' => 'Tech Corp',
'emails' => [
'john.doe@example.com'
],
'work_email' => 'john@techcorp.com',
'work_phone' => '+1-555-0100',
'personal_email' => 'john.doe@gmail.com',
'mobile_phone' => '+1-555-0123',
'phone_numbers' => [
'+1-555-0199'
],
'notes' => 'Strong backend experience, open to relocation.',
'job_id' => '345e6789-e01b-23c4-d567-890123456789',
'external_source_id' => 'ext-candidate-12345',
'enrich_record' => true,
'person_owner' => '234e5678-e90a-12b3-c456-789012345678',
'sourced_by' => '234e5678-e90a-12b3-c456-789012345678',
'custom_fields' => [
[
'attribute_id' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
'value' => 'Senior'
],
[
'attribute_id' => 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
'value' => 8
],
[
'attribute_id' => 'c3d4e5f6-a7b8-9012-cdef-234567890123',
'add_company_ids' => [
'456e7890-e12b-34d5-a678-901234567890'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.stardex.ai/v1/persons"
payload := strings.NewReader("{\n \"name\": \"John Doe\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"linkedin_url\": \"https://www.linkedin.com/in/johndoe\",\n \"current_job_title\": \"Software Engineer\",\n \"location\": \"San Francisco, CA\",\n \"company_name\": \"Tech Corp\",\n \"emails\": [\n \"john.doe@example.com\"\n ],\n \"work_email\": \"john@techcorp.com\",\n \"work_phone\": \"+1-555-0100\",\n \"personal_email\": \"john.doe@gmail.com\",\n \"mobile_phone\": \"+1-555-0123\",\n \"phone_numbers\": [\n \"+1-555-0199\"\n ],\n \"notes\": \"Strong backend experience, open to relocation.\",\n \"job_id\": \"345e6789-e01b-23c4-d567-890123456789\",\n \"external_source_id\": \"ext-candidate-12345\",\n \"enrich_record\": true,\n \"person_owner\": \"234e5678-e90a-12b3-c456-789012345678\",\n \"sourced_by\": \"234e5678-e90a-12b3-c456-789012345678\",\n \"custom_fields\": [\n {\n \"attribute_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"value\": \"Senior\"\n },\n {\n \"attribute_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n \"value\": 8\n },\n {\n \"attribute_id\": \"c3d4e5f6-a7b8-9012-cdef-234567890123\",\n \"add_company_ids\": [\n \"456e7890-e12b-34d5-a678-901234567890\"\n ]\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.stardex.ai/v1/persons")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"John Doe\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"linkedin_url\": \"https://www.linkedin.com/in/johndoe\",\n \"current_job_title\": \"Software Engineer\",\n \"location\": \"San Francisco, CA\",\n \"company_name\": \"Tech Corp\",\n \"emails\": [\n \"john.doe@example.com\"\n ],\n \"work_email\": \"john@techcorp.com\",\n \"work_phone\": \"+1-555-0100\",\n \"personal_email\": \"john.doe@gmail.com\",\n \"mobile_phone\": \"+1-555-0123\",\n \"phone_numbers\": [\n \"+1-555-0199\"\n ],\n \"notes\": \"Strong backend experience, open to relocation.\",\n \"job_id\": \"345e6789-e01b-23c4-d567-890123456789\",\n \"external_source_id\": \"ext-candidate-12345\",\n \"enrich_record\": true,\n \"person_owner\": \"234e5678-e90a-12b3-c456-789012345678\",\n \"sourced_by\": \"234e5678-e90a-12b3-c456-789012345678\",\n \"custom_fields\": [\n {\n \"attribute_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"value\": \"Senior\"\n },\n {\n \"attribute_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n \"value\": 8\n },\n {\n \"attribute_id\": \"c3d4e5f6-a7b8-9012-cdef-234567890123\",\n \"add_company_ids\": [\n \"456e7890-e12b-34d5-a678-901234567890\"\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.stardex.ai/v1/persons")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"John Doe\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"linkedin_url\": \"https://www.linkedin.com/in/johndoe\",\n \"current_job_title\": \"Software Engineer\",\n \"location\": \"San Francisco, CA\",\n \"company_name\": \"Tech Corp\",\n \"emails\": [\n \"john.doe@example.com\"\n ],\n \"work_email\": \"john@techcorp.com\",\n \"work_phone\": \"+1-555-0100\",\n \"personal_email\": \"john.doe@gmail.com\",\n \"mobile_phone\": \"+1-555-0123\",\n \"phone_numbers\": [\n \"+1-555-0199\"\n ],\n \"notes\": \"Strong backend experience, open to relocation.\",\n \"job_id\": \"345e6789-e01b-23c4-d567-890123456789\",\n \"external_source_id\": \"ext-candidate-12345\",\n \"enrich_record\": true,\n \"person_owner\": \"234e5678-e90a-12b3-c456-789012345678\",\n \"sourced_by\": \"234e5678-e90a-12b3-c456-789012345678\",\n \"custom_fields\": [\n {\n \"attribute_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"value\": \"Senior\"\n },\n {\n \"attribute_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\",\n \"value\": 8\n },\n {\n \"attribute_id\": \"c3d4e5f6-a7b8-9012-cdef-234567890123\",\n \"add_company_ids\": [\n \"456e7890-e12b-34d5-a678-901234567890\"\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "John Doe",
"linkedin_public_id": "johndoe",
"current_job_title": "Software Engineer",
"company_name": "Tech Corp",
"location": "San Francisco, CA",
"emails": [
{
"contact_data_type": "work",
"value": "john@techcorp.com"
}
],
"phones": [
{
"contact_data_type": "mobile",
"value": "+1-555-0123"
}
],
"candidate_id": "789e0123-e45f-67a8-b901-234567890123",
"client_contact_id": null,
"external_source_id": null
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "PERSON_DELETION_REQUESTED",
"message": "This person asked to be removed from your workspace and can't be added again."
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}Authorizations
Authenticate with a Bearer token: API key, OAuth token, or session token.
Body
application/json
Full name (required). Used as display name across the system.
Minimum string length:
1First name. Auto-split from name if omitted.
Last name. Auto-split from name if omitted.
Strongly recommended. LinkedIn profile URL (e.g. "https://linkedin.com/in/johndoe") is the deduplication key for this endpoint. When present, an existing person with that profile is matched and updated (never duplicated), including when job_id is used to add a candidacy. Without it, a duplicate is only caught when the name matches an existing person along with their email and/or phone (see the endpoint description); otherwise a new person is created. Enrichment is also skipped without a LinkedIn URL.
Current job title.
Location (e.g. city, region, or country).
Current employer company name.
Additional email addresses.
Primary work email.
Work phone number.
Personal email address.
Mobile phone number.
Additional phone numbers.
Initial note to attach to the person record.
Job UUID to add this person to that job pipeline as a candidate (creates the candidacy). When linkedin_url is provided, works whether the person is new or already exists (matched by linkedin_url, never duplicated). Without linkedin_url, a new person may be created unless it is automatically merged into a matching existing person, in which case that person is added to the job. Get IDs from POST /v1/jobs/search.
Job title to match and add this person to that job pipeline as a candidate. Used when job_id is not provided.
Company name to associate this person as a client contact.
Company UUID for client contact association. Get IDs from GET /v1/companies.
Identifier from an external system (e.g. HRIS or legacy ATS). A new person is never automatically merged into an existing person that has a different external_source_id.
When true, triggers background enrichment via data providers after creation.
UUID of the team member to assign as owner of this person. Get IDs from GET /v1/team-members. If omitted, the caller is auto-assigned when authenticated as a team member. If the team member is not found, a warning is logged but person creation still proceeds.
UUID of the team member who sourced this candidate, recorded as "Sourced by" on the new candidacy. Get IDs from GET /v1/team-members. Requires job_id. Only applies to API-key requests; requests made as a signed-in user (session or OAuth, including MCP) always credit that user. If the person is already a candidate on the job, the existing sourcer is kept. When person_owner is omitted, this team member also becomes the owner of a newly created person and candidacy.
Custom field values to set, in the same shape as PATCH /v1/persons/{id}. Get attribute definitions from GET /v1/custom-fields/persons. When linkedin_url matches an existing person, the values are written to that person. If a value is invalid, the person is still saved and the error message includes its ID so the fields can be retried with PATCH.
Show child attributes
Show child attributes
Was this page helpful?