Create Contact

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" }
  }'

const res = await fetch('https://api.usegately.com/api/v1/contacts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'X-Project-ID': 'YOUR_PROJECT_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Jane Smith',
    email: 'jane@example.com',
    company: 'Acme Corp',
    status: 'active',
    tags: ['VIP', 'Newsletter'],
    custom_fields: { plan: 'pro' },
  }),
})
const contact = await res.json()

import { GatelyContacts } from '@gately/sdk'

const crm = new GatelyContacts({ projectId: 'YOUR_PROJECT_ID' })

const contact = await crm.create({
  name: 'Jane Smith',
  email: 'jane@example.com',
  company: 'Acme Corp',
  status: 'active',
  tags: ['VIP', 'Newsletter'],
  custom_fields: { plan: 'pro', source: 'webinar' },
})

{
  "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"
}

{
  "error": "A contact with this email already exists"
}

POST

api

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" }
  }'

const res = await fetch('https://api.usegately.com/api/v1/contacts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'X-Project-ID': 'YOUR_PROJECT_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Jane Smith',
    email: 'jane@example.com',
    company: 'Acme Corp',
    status: 'active',
    tags: ['VIP', 'Newsletter'],
    custom_fields: { plan: 'pro' },
  }),
})
const contact = await res.json()

import { GatelyContacts } from '@gately/sdk'

const crm = new GatelyContacts({ projectId: 'YOUR_PROJECT_ID' })

const contact = await crm.create({
  name: 'Jane Smith',
  email: 'jane@example.com',
  company: 'Acme Corp',
  status: 'active',
  tags: ['VIP', 'Newsletter'],
  custom_fields: { plan: 'pro', source: 'webinar' },
})

{
  "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"
}

{
  "error": "A contact with this email already exists"
}

Headers

string

required

Bearer YOUR_API_KEY

string

Your project UUID. Not required if the API key already encodes the project.

Request Body

string

required

Full name of the contact

string

required

Email address — must be unique within the project

string

Phone number

string

Mobile number

string

Company or organisation name

string

default:"new"

new · active · inactive · archived

string

Internal notes visible only to your team

string

First name (stored separately from name)

string

Last name

string

Street address line 1

string

Street address line 2

string

City

string

State or province

string

Postal / ZIP code

string

Country

object

Arbitrary key-value pairs (e.g. { "plan": "pro", "source": "webinar" })

string[]

Tag names to attach on creation. Tags are created automatically if they don’t exist.

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" }
  }'

const res = await fetch('https://api.usegately.com/api/v1/contacts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'X-Project-ID': 'YOUR_PROJECT_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Jane Smith',
    email: 'jane@example.com',
    company: 'Acme Corp',
    status: 'active',
    tags: ['VIP', 'Newsletter'],
    custom_fields: { plan: 'pro' },
  }),
})
const contact = await res.json()

import { GatelyContacts } from '@gately/sdk'

const crm = new GatelyContacts({ projectId: 'YOUR_PROJECT_ID' })

const contact = await crm.create({
  name: 'Jane Smith',
  email: 'jane@example.com',
  company: 'Acme Corp',
  status: 'active',
  tags: ['VIP', 'Newsletter'],
  custom_fields: { plan: 'pro', source: 'webinar' },
})

{
  "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"
}

{
  "error": "A contact with this email already exists"
}

Overview

Authentication

Members

Project Settings

Email Campaigns

Plans

Contacts

Discussions

Transactional Email

Webhooks

Headers

Request Body

Response

​Headers

​Request Body

​Response

Headers

Request Body

Response