Create client contact

curl --request POST \
  --url https://api.stardex.ai/v1/client-contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "person_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "client_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "client_contact_status_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "owner_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'

import requests

url = "https://api.stardex.ai/v1/client-contacts"

payload = {
    "person_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "client_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "client_contact_status_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "owner_ids": ["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({
    person_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    client_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    client_contact_status_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    owner_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a']
  })
};

fetch('https://api.stardex.ai/v1/client-contacts', 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/client-contacts",
  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([
    'person_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'client_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'client_contact_status_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'owner_ids' => [
        '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/client-contacts"

	payload := strings.NewReader("{\n  \"person_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"client_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"client_contact_status_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"owner_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\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/client-contacts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"person_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"client_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"client_contact_status_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"owner_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.stardex.ai/v1/client-contacts")

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  \"person_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"client_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"client_contact_status_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"owner_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "id": "ab12cd34-ef56-7890-ab12-cd34ef567890",
    "person_id": "fff66666-0000-1111-2222-333333336666",
    "client_id": "bbb22222-cccc-dddd-eeee-ffffffff2222",
    "client_contact_status_id": "890e1234-f56a-78b9-c012-345678901234",
    "owner_ids": [
      "ddd44444-eeee-ffff-0000-111111114444"
    ],
    "created_at": "2024-01-15T10:00:00Z",
    "is_new": false
  }
}

{
  "success": true,
  "data": {
    "id": "ab12cd34-ef56-7890-ab12-cd34ef567890",
    "person_id": "fff66666-0000-1111-2222-333333336666",
    "client_id": "bbb22222-cccc-dddd-eeee-ffffffff2222",
    "client_contact_status_id": "890e1234-f56a-78b9-c012-345678901234",
    "owner_ids": [
      "ddd44444-eeee-ffff-0000-111111114444"
    ],
    "created_at": "2024-01-15T10:00:00Z",
    "is_new": true
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Client Contacts

Create client contact

Promote an existing person into a client contact by linking them to a client company. The associated company is automatically flagged as a client.

Idempotency: A person can be an active client contact for at most one client company per team (DB constraint). If a non-deleted client contact already exists for this person, the existing record is returned with is_new: false and the echoed client_id reflects the contact’s actual client company — compare it to the requested client_id to detect mismatches. New contacts return 201 with is_new: true; existing contacts return 200.

Status: When client_contact_status_id is omitted, the team default status is assigned. Pass null to leave the new contact without a status.

Owners: When owner_ids is omitted, the authenticated caller is auto-assigned (if they are a team member). Pass an empty array to create a contact with no owners.

POST

client-contacts

Create client contact

curl --request POST \
  --url https://api.stardex.ai/v1/client-contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "person_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "client_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "client_contact_status_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "owner_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'

import requests

url = "https://api.stardex.ai/v1/client-contacts"

payload = {
    "person_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "client_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "client_contact_status_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "owner_ids": ["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({
    person_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    client_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    client_contact_status_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    owner_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a']
  })
};

fetch('https://api.stardex.ai/v1/client-contacts', 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/client-contacts",
  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([
    'person_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'client_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'client_contact_status_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'owner_ids' => [
        '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/client-contacts"

	payload := strings.NewReader("{\n  \"person_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"client_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"client_contact_status_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"owner_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\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/client-contacts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"person_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"client_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"client_contact_status_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"owner_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.stardex.ai/v1/client-contacts")

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  \"person_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"client_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"client_contact_status_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"owner_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "id": "ab12cd34-ef56-7890-ab12-cd34ef567890",
    "person_id": "fff66666-0000-1111-2222-333333336666",
    "client_id": "bbb22222-cccc-dddd-eeee-ffffffff2222",
    "client_contact_status_id": "890e1234-f56a-78b9-c012-345678901234",
    "owner_ids": [
      "ddd44444-eeee-ffff-0000-111111114444"
    ],
    "created_at": "2024-01-15T10:00:00Z",
    "is_new": false
  }
}

{
  "success": true,
  "data": {
    "id": "ab12cd34-ef56-7890-ab12-cd34ef567890",
    "person_id": "fff66666-0000-1111-2222-333333336666",
    "client_id": "bbb22222-cccc-dddd-eeee-ffffffff2222",
    "client_contact_status_id": "890e1234-f56a-78b9-c012-345678901234",
    "owner_ids": [
      "ddd44444-eeee-ffff-0000-111111114444"
    ],
    "created_at": "2024-01-15T10:00:00Z",
    "is_new": true
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Authenticate with a Bearer token: API key, OAuth token, or session token.

Body

application/json

person_id

string<uuid>

required

Person UUID to promote into a client contact. Get IDs from POST /v1/persons/search or POST /v1/persons.

client_id

string<uuid>

required

Client company UUID this person belongs to. Get IDs from GET /v1/companies. The company is automatically flagged as a client when this contact is created.

client_contact_status_id

string<uuid> | null

Optional client contact status UUID. When omitted, the team default status is used. Use GET /v1/client-contacts/statuses to discover available status IDs.

owner_ids

string<uuid>[]

Optional team member UUIDs to assign as client-contact owners. If omitted, the authenticated caller (when they are a team member) is auto-assigned.

Response

Existing client contact returned (no duplicate created)

success

enum<boolean>

required

Available options:

true

data

object

required

Show child attributes

List client contact statuses Update client contact status

API Documentation

Activity Reports

Calendar Meetings

Candidates

Client Contacts

Companies

Company Activities

Company Insights

Custom Fields

Deal Activities

Deals

Job Activities

Jobs

Lists

Meeting Recordings

Person Activities

Persons

Scorecards

Tasks

Team Members

Webhooks

Create client contact

Authorizations

Body

Response