Contacts

Contacts represent individual people in your CRM. Each contact can have an email, phone number, company association, custom fields, and tags.

Data Model

Field	Type	Description
`id`	`string`	Unique ID with `ct_` prefix
`email`	`string \| null`	Email address (unique per workspace)
`first_name`	`string \| null`	First name (max 100 chars)
`last_name`	`string \| null`	Last name (max 100 chars)
`phone`	`string \| null`	Phone number (max 50 chars)
`company_id`	`string \| null`	Associated company ID (`co_` prefix)
`title`	`string \| null`	Job title (max 200 chars)
`source`	`string \| null`	Lead source (max 100 chars)
`custom_fields`	`object`	Custom field key-value pairs
`tags`	`string[]`	Tags for categorization (max 20, each max 50 chars)
`created_at`	`string`	ISO 8601 timestamp
`updated_at`	`string`	ISO 8601 timestamp

Create a Contact

curl -X POST https://api.nodestash.io/v1/contacts \
  -H "Authorization: Bearer $NODESTASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@acme.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+1-555-0100",
    "title": "VP of Engineering",
    "source": "website",
    "tags": ["prospect", "enterprise"]
  }'

const contact = await client.contacts.create({
  email: 'jane@acme.com',
  first_name: 'Jane',
  last_name: 'Doe',
  phone: '+1-555-0100',
  title: 'VP of Engineering',
  source: 'website',
  tags: ['prospect', 'enterprise'],
})

Link to a Company

Associate a contact with a company by setting company_id:

curl -X PATCH https://api.nodestash.io/v1/contacts/ct_abc123 \
  -H "Authorization: Bearer $NODESTASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "co_xyz789"
  }'

await client.contacts.update('ct_abc123', {
  company_id: 'co_xyz789',
})

Search and Filter

List contacts with filters for email, name, company, source, and tags:

# Filter by email domain (substring match)
curl "https://api.nodestash.io/v1/contacts?email=acme.com&sort=-created_at&limit=50" \
  -H "Authorization: Bearer $NODESTASH_API_KEY"

# Filter by tags (requires ALL specified tags)
curl "https://api.nodestash.io/v1/contacts?tags=prospect,enterprise" \
  -H "Authorization: Bearer $NODESTASH_API_KEY"

// Filter by email domain
const { data } = await client.contacts.list({
  email: 'acme.com',
  sort: '-created_at',
  limit: 50,
})

// Filter by tags (requires ALL specified tags)
const { data: tagged } = await client.contacts.list({
  tags: 'prospect,enterprise',
})

// Iterate all contacts matching filters
for await (const contact of client.contacts.listAll({
  source: 'website',
})) {
  console.log(contact.email)
}

Available Filters

Parameter	Match Type	Description
`email`	Substring (case-insensitive)	Filter by email
`first_name`	Substring (case-insensitive)	Filter by first name
`last_name`	Substring (case-insensitive)	Filter by last name
`company_id`	Exact	Filter by company
`source`	Exact	Filter by lead source
`tags`	All match	Comma-separated, contact must have all

Sorting

Use the sort parameter with - prefix for descending:

created_at / -created_at
updated_at / -updated_at
email / -email
first_name / -first_name
last_name / -last_name

Custom Fields

Add custom data to contacts using Custom Fields:

# Set custom field values
curl -X PUT https://api.nodestash.io/v1/contacts/ct_abc123/custom-fields \
  -H "Authorization: Bearer $NODESTASH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "vip_level": "Gold",
      "customer_since": "2024-01-15"
    }
  }'

await client.customFields.values.set('contacts', 'ct_abc123', {
  fields: {
    vip_level: 'Gold',
    customer_since: '2024-01-15',
  },
})

API Reference

List Contacts

GET /v1/contacts

Create Contact

POST /v1/contacts

Get Contact

GET /v1/contacts/{id}

Update Contact

PATCH /v1/contacts/{id}

Delete Contact

DELETE /v1/contacts/{id}

List Contacts

Create Contact

Get Contact

Update Contact

Delete Contact

On this page