Skip to main content
POST
/
api
/
v1
/
contacts
curl -X POST "https://api.usegately.com/api/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "company": "Acme Corp",
    "status": "active",
    "tags": ["VIP", "Newsletter"],
    "custom_fields": { "plan": "pro" }
  }'

{
  "id": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "project_id": "proj-uuid-here",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "company": "Acme Corp",
  "status": "active",
  "custom_fields": { "plan": "pro", "source": "webinar" },
  "unsubscribed": false,
  "created_at": "2025-06-01T10:00:00.000Z",
  "updated_at": "2025-06-01T10:00:00.000Z"
}

​
Headers

​
Authorization
string
required
Bearer YOUR_API_KEY
​
X-Project-ID
string
Your project UUID. Not required if the API key already encodes the project.

​
Request Body

​
name
string
required
Full name of the contact
​
email
string
required
Email address — must be unique within the project
​
phone
string
Phone number
​
mobile
string
Mobile number
​
company
string
Company or organisation name
​
status
string
default:"new"
new · active · inactive · archived
​
notes
string
Internal notes visible only to your team
​
first_name
string
First name (stored separately from name)
​
last_name
string
Last name
​
address_line_1
string
Street address line 1
​
address_line_2
string
Street address line 2
​
city
string
City
​
state
string
State or province
​
zip
string
Postal / ZIP code
​
country
string
Country
​
custom_fields
object
Arbitrary key-value pairs (e.g. { "plan": "pro", "source": "webinar" })
​
tags
string[]
Tag names to attach on creation. Tags are created automatically if they don’t exist.
​
external_id
string
Your own identifier for this contact (e.g. a user ID from your database)

​
Response

Returns the created contact object. 
curl -X POST "https://api.usegately.com/api/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Project-ID: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "company": "Acme Corp",
    "status": "active",
    "tags": ["VIP", "Newsletter"],
    "custom_fields": { "plan": "pro" }
  }'

{
  "id": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
  "project_id": "proj-uuid-here",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "company": "Acme Corp",
  "status": "active",
  "custom_fields": { "plan": "pro", "source": "webinar" },
  "unsubscribed": false,
  "created_at": "2025-06-01T10:00:00.000Z",
  "updated_at": "2025-06-01T10:00:00.000Z"
}