Create person
curl --request POST \
--url https://api.stardex.ai/v1/persons \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"linkedin_url": "<string>",
"current_job_title": "<string>",
"location": "<string>",
"company_name": "<string>",
"emails": [
"jsmith@example.com"
],
"work_email": "jsmith@example.com",
"work_phone": "<string>",
"personal_email": "jsmith@example.com",
"mobile_phone": "<string>",
"phone_numbers": [
"<string>"
],
"notes": "<string>",
"job_id": "<string>",
"job_name": "<string>",
"client_name": "<string>",
"client_id": "<string>",
"external_source_id": "<string>",
"enrich_record": true,
"person_owner": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'import requests
url = "https://api.stardex.ai/v1/persons"
payload = {
"name": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"linkedin_url": "<string>",
"current_job_title": "<string>",
"location": "<string>",
"company_name": "<string>",
"emails": ["jsmith@example.com"],
"work_email": "jsmith@example.com",
"work_phone": "<string>",
"personal_email": "jsmith@example.com",
"mobile_phone": "<string>",
"phone_numbers": ["<string>"],
"notes": "<string>",
"job_id": "<string>",
"job_name": "<string>",
"client_name": "<string>",
"client_id": "<string>",
"external_source_id": "<string>",
"enrich_record": True,
"person_owner": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
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: '<string>',
first_name: '<string>',
last_name: '<string>',
linkedin_url: '<string>',
current_job_title: '<string>',
location: '<string>',
company_name: '<string>',
emails: ['jsmith@example.com'],
work_email: 'jsmith@example.com',
work_phone: '<string>',
personal_email: 'jsmith@example.com',
mobile_phone: '<string>',
phone_numbers: ['<string>'],
notes: '<string>',
job_id: '<string>',
job_name: '<string>',
client_name: '<string>',
client_id: '<string>',
external_source_id: '<string>',
enrich_record: true,
person_owner: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
})
};
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' => '<string>',
'first_name' => '<string>',
'last_name' => '<string>',
'linkedin_url' => '<string>',
'current_job_title' => '<string>',
'location' => '<string>',
'company_name' => '<string>',
'emails' => [
'jsmith@example.com'
],
'work_email' => 'jsmith@example.com',
'work_phone' => '<string>',
'personal_email' => 'jsmith@example.com',
'mobile_phone' => '<string>',
'phone_numbers' => [
'<string>'
],
'notes' => '<string>',
'job_id' => '<string>',
'job_name' => '<string>',
'client_name' => '<string>',
'client_id' => '<string>',
'external_source_id' => '<string>',
'enrich_record' => true,
'person_owner' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
]),
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\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"current_job_title\": \"<string>\",\n \"location\": \"<string>\",\n \"company_name\": \"<string>\",\n \"emails\": [\n \"jsmith@example.com\"\n ],\n \"work_email\": \"jsmith@example.com\",\n \"work_phone\": \"<string>\",\n \"personal_email\": \"jsmith@example.com\",\n \"mobile_phone\": \"<string>\",\n \"phone_numbers\": [\n \"<string>\"\n ],\n \"notes\": \"<string>\",\n \"job_id\": \"<string>\",\n \"job_name\": \"<string>\",\n \"client_name\": \"<string>\",\n \"client_id\": \"<string>\",\n \"external_source_id\": \"<string>\",\n \"enrich_record\": true,\n \"person_owner\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\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\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"current_job_title\": \"<string>\",\n \"location\": \"<string>\",\n \"company_name\": \"<string>\",\n \"emails\": [\n \"jsmith@example.com\"\n ],\n \"work_email\": \"jsmith@example.com\",\n \"work_phone\": \"<string>\",\n \"personal_email\": \"jsmith@example.com\",\n \"mobile_phone\": \"<string>\",\n \"phone_numbers\": [\n \"<string>\"\n ],\n \"notes\": \"<string>\",\n \"job_id\": \"<string>\",\n \"job_name\": \"<string>\",\n \"client_name\": \"<string>\",\n \"client_id\": \"<string>\",\n \"external_source_id\": \"<string>\",\n \"enrich_record\": true,\n \"person_owner\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\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\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"current_job_title\": \"<string>\",\n \"location\": \"<string>\",\n \"company_name\": \"<string>\",\n \"emails\": [\n \"jsmith@example.com\"\n ],\n \"work_email\": \"jsmith@example.com\",\n \"work_phone\": \"<string>\",\n \"personal_email\": \"jsmith@example.com\",\n \"mobile_phone\": \"<string>\",\n \"phone_numbers\": [\n \"<string>\"\n ],\n \"notes\": \"<string>\",\n \"job_id\": \"<string>\",\n \"job_name\": \"<string>\",\n \"client_name\": \"<string>\",\n \"client_id\": \"<string>\",\n \"external_source_id\": \"<string>\",\n \"enrich_record\": true,\n \"person_owner\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\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>"
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>"
}
}Persons
Create person
Create a new person record with contact details and optional job association. Returns the created person with IDs for further operations.
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). Omitting it will create a new person even if the same person already exists (including matches on name or email), leading to more duplicates. 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": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"linkedin_url": "<string>",
"current_job_title": "<string>",
"location": "<string>",
"company_name": "<string>",
"emails": [
"jsmith@example.com"
],
"work_email": "jsmith@example.com",
"work_phone": "<string>",
"personal_email": "jsmith@example.com",
"mobile_phone": "<string>",
"phone_numbers": [
"<string>"
],
"notes": "<string>",
"job_id": "<string>",
"job_name": "<string>",
"client_name": "<string>",
"client_id": "<string>",
"external_source_id": "<string>",
"enrich_record": true,
"person_owner": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'import requests
url = "https://api.stardex.ai/v1/persons"
payload = {
"name": "<string>",
"first_name": "<string>",
"last_name": "<string>",
"linkedin_url": "<string>",
"current_job_title": "<string>",
"location": "<string>",
"company_name": "<string>",
"emails": ["jsmith@example.com"],
"work_email": "jsmith@example.com",
"work_phone": "<string>",
"personal_email": "jsmith@example.com",
"mobile_phone": "<string>",
"phone_numbers": ["<string>"],
"notes": "<string>",
"job_id": "<string>",
"job_name": "<string>",
"client_name": "<string>",
"client_id": "<string>",
"external_source_id": "<string>",
"enrich_record": True,
"person_owner": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
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: '<string>',
first_name: '<string>',
last_name: '<string>',
linkedin_url: '<string>',
current_job_title: '<string>',
location: '<string>',
company_name: '<string>',
emails: ['jsmith@example.com'],
work_email: 'jsmith@example.com',
work_phone: '<string>',
personal_email: 'jsmith@example.com',
mobile_phone: '<string>',
phone_numbers: ['<string>'],
notes: '<string>',
job_id: '<string>',
job_name: '<string>',
client_name: '<string>',
client_id: '<string>',
external_source_id: '<string>',
enrich_record: true,
person_owner: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
})
};
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' => '<string>',
'first_name' => '<string>',
'last_name' => '<string>',
'linkedin_url' => '<string>',
'current_job_title' => '<string>',
'location' => '<string>',
'company_name' => '<string>',
'emails' => [
'jsmith@example.com'
],
'work_email' => 'jsmith@example.com',
'work_phone' => '<string>',
'personal_email' => 'jsmith@example.com',
'mobile_phone' => '<string>',
'phone_numbers' => [
'<string>'
],
'notes' => '<string>',
'job_id' => '<string>',
'job_name' => '<string>',
'client_name' => '<string>',
'client_id' => '<string>',
'external_source_id' => '<string>',
'enrich_record' => true,
'person_owner' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
]),
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\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"current_job_title\": \"<string>\",\n \"location\": \"<string>\",\n \"company_name\": \"<string>\",\n \"emails\": [\n \"jsmith@example.com\"\n ],\n \"work_email\": \"jsmith@example.com\",\n \"work_phone\": \"<string>\",\n \"personal_email\": \"jsmith@example.com\",\n \"mobile_phone\": \"<string>\",\n \"phone_numbers\": [\n \"<string>\"\n ],\n \"notes\": \"<string>\",\n \"job_id\": \"<string>\",\n \"job_name\": \"<string>\",\n \"client_name\": \"<string>\",\n \"client_id\": \"<string>\",\n \"external_source_id\": \"<string>\",\n \"enrich_record\": true,\n \"person_owner\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\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\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"current_job_title\": \"<string>\",\n \"location\": \"<string>\",\n \"company_name\": \"<string>\",\n \"emails\": [\n \"jsmith@example.com\"\n ],\n \"work_email\": \"jsmith@example.com\",\n \"work_phone\": \"<string>\",\n \"personal_email\": \"jsmith@example.com\",\n \"mobile_phone\": \"<string>\",\n \"phone_numbers\": [\n \"<string>\"\n ],\n \"notes\": \"<string>\",\n \"job_id\": \"<string>\",\n \"job_name\": \"<string>\",\n \"client_name\": \"<string>\",\n \"client_id\": \"<string>\",\n \"external_source_id\": \"<string>\",\n \"enrich_record\": true,\n \"person_owner\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\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\": \"<string>\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"linkedin_url\": \"<string>\",\n \"current_job_title\": \"<string>\",\n \"location\": \"<string>\",\n \"company_name\": \"<string>\",\n \"emails\": [\n \"jsmith@example.com\"\n ],\n \"work_email\": \"jsmith@example.com\",\n \"work_phone\": \"<string>\",\n \"personal_email\": \"jsmith@example.com\",\n \"mobile_phone\": \"<string>\",\n \"phone_numbers\": [\n \"<string>\"\n ],\n \"notes\": \"<string>\",\n \"job_id\": \"<string>\",\n \"job_name\": \"<string>\",\n \"client_name\": \"<string>\",\n \"client_id\": \"<string>\",\n \"external_source_id\": \"<string>\",\n \"enrich_record\": true,\n \"person_owner\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\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>"
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>"
}
}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. Omitting it will create a new person even if the same person already exists, including matches on name or email — leading to more duplicates. 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 even if a duplicate already exists. 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).
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.
Was this page helpful?