POST/v1/contactscontacts:write

Create a contact

Creates a new contact. Email is the dedupe key — if a contact with the same `email` already exists, the request is idempotently merged onto the existing row (additional emails / phones unioned, blank fields filled).

Run a request

POST/v1/contacts

Base URL

Request body (JSON)

Resolved URL

POSThttps://coldos.justgotwyrd.com/api/v1/contacts

Paste an API key in the bar at the top of the page to enable Execute.

Parameters

Body parameters

emailstringrequired
Primary email. Lowercased and trimmed before dedupe.
first_namestringoptional
Given name.
last_namestringoptional
Family name.
titlestringoptional
Job title.
phonestringoptional
Primary phone, in E.164.
organization_iduuidoptional
Link to an existing organization.
tagsstring[]optional
Tag names to attach. Created on demand.
owner_iduuidoptional
Defaults to the API key's owner. Pass `null` to leave unowned.

Responses

201Created (or merged onto an existing row).
400Invalid request — see `error.message`.
401Missing or invalid API key.
403Authenticated, but the key lacks the required scope.
404The referenced resource does not exist or is not visible to your key.
429Rate limit exceeded — see `Retry-After`.
500Unexpected server error. Safe to retry with idempotency-key.

Code samples

curl -X POST "https://coldos.justgotwyrd.com/api/v1/contacts" \
  -H "Authorization: Bearer $COLD_OS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "email": "ankit@example.com",
      "first_name": "Ankit",
      "last_name": "Bhardwaj",
      "title": "Head of Growth",
      "phone": "+919555516408",
      "organization_id": "9b2e1cd4-3c9b-4a1d-9b2f-21efae55c012",
      "tags": [
        "high-intent"
      ]
    }'

Response · 200

{
  "id": "c2a8a93a-2f1c-4c5b-8f3d-9c1e3a8b5d12",
  "email": "ankit@example.com",
  "full_name": "Ankit Bhardwaj",
  "first_name": "Ankit",
  "last_name": "Bhardwaj",
  "title": "Head of Growth",
  "phone": "+919555516408",
  "mobile_phone": null,
  "whatsapp_number": "+919555516408",
  "linkedin_url": "https://www.linkedin.com/in/ankitbhardwaj",
  "organization_id": "9b2e1cd4-3c9b-4a1d-9b2f-21efae55c012",
  "internal_stage": "meeting_booked",
  "owner_id": "b1f2c3d4-5678-90ab-cdef-1234567890ab",
  "tags": [
    "high-intent",
    "warm-intro"
  ],
  "additional_emails": [],
  "additional_phones": [],
  "custom_fields": {
    "region": "APAC",
    "priority_score": 87
  },
  "last_engagement_at": "2026-05-01T14:30:00.000+05:30",
  "created_at": "2026-04-12T09:11:00.000+05:30",
  "updated_at": "2026-05-01T14:30:00.000+05:30"
}

Was this page helpful?

Your vote stays in this browser. We'll use it to prioritise rewrites.