Create Contact

POST /external/v1/contacts

Creates a new contact in your account.

Retry-safe

Send an Idempotency-Key header to make retries safe — a repeated request with the same key replays the original response instead of creating a duplicate.

Authentication

Requires contacts:write permission.

Request Body

Field	Type	Required	Description
name	string	Yes	Full name of the contact
email	string	No	Email address
phone	string	No	Phone number with country code
company	string	No	Company name
title	string	No	Job title/position
location	string	No	Location
linkedin_profile_url	string	No	LinkedIn profile URL
source	string	No	Lead source (default: api)
tags	array	No	Array of tag IDs (UUIDs) to attach
custom_fields	object	No	Custom field key-value pairs

Request

cURL

curl --request POST \
  --url "https://app.getraze.com/external/v1/contacts" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: YOUR_API_KEY" \
  --data '{
    "name": "Jane Smith",
    "email": "jane@company.com",
    "phone": "+5511988888888",
    "company": "Tech Corp",
    "title": "CTO",
    "tags": ["tag_01", "tag_02"]
  }'

Node.js

const axios = require('axios');

const response = await axios.post(
  'https://app.getraze.com/external/v1/contacts',
  {
    name: 'Jane Smith',
    email: 'jane@company.com',
    phone: '+5511988888888',
    company: 'Tech Corp',
    title: 'CTO',
    tags: ['tag_01', 'tag_02']
  },
  {
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);

Python

import requests

response = requests.post(
    'https://app.getraze.com/external/v1/contacts',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Jane Smith',
        'email': 'jane@company.com',
        'phone': '+5511988888888',
        'company': 'Tech Corp',
        'title': 'CTO',
        'tags': ['tag_01', 'tag_02']
    }
)

print(response.json())

Response

{
  "success": true,
  "data": {
    "id": "cnt_xyz789abc123",
    "name": "Jane Smith",
    "email": "jane@company.com",
    "phone": "+5511988888888",
    "company": "Tech Corp",
    "title": "CTO",
    "location": null,
    "linkedin_profile_url": null,
    "source": "api",
    "custom_fields": null,
    "created_at": "2026-01-25T09:00:00Z",
    "updated_at": "2026-01-25T09:00:00Z",
    "tags": [
      { "id": "tag_01", "name": "hot-lead", "color": "red" }
    ]
  }
}

The response returns the full contact record together with the resolved tags objects.

Errors

Status	Code	Description
400	VALIDATION_ERROR	name is missing or empty
409	DUPLICATE_ERROR	A contact with this email already exists