Public API

Create contacts in FollowThrough

Use the Contacts API to send enriched leads or customers into a FollowThrough workspace. Requests are scoped by the API key, so partners do not need to choose a destination account in the payload.

Endpoint

https://follow.clvrd.com/api/v1/contacts

Authentication

Send an API key in the Authorization header as a Bearer token.

Account Routing

The API key determines the destination user or workspace. No account_id field is required.

Environment Values

FOLLOWTHROUGH_CONTACTS_ENDPOINT	https://follow.clvrd.com/api/v1/contacts
FOLLOWTHROUGH_API_TOKEN	Create this in FollowThrough under Settings, API Keys. It starts with `ft_live_`.
FOLLOWTHROUGH_ACCOUNT_ID	Not required by FollowThrough. The Bearer token routes contacts to the correct account or workspace.

Create Contact

Send a POST request with JSON. If a contact already exists with the same email, FollowThrough updates the existing record instead of creating a duplicate.

curl -X POST https://follow.clvrd.com/api/v1/contacts \
  -H "Authorization: Bearer ft_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Dana",
    "last_name": "Pourjafar",
    "email": "lead@example.com",
    "phone": "+16045550123",
    "company_name": "Example Co",
    "segments": ["VIP", "Enriched lead"],
    "source": "enrichment_partner",
    "stage_type": "lead",
    "pipeline_key": "sales"
  }'

Accepted Fields

Field	Type	Notes
first_name	string	Required if email is missing. Used to create the contact name.
last_name	string	Optional.
full_name	string	Optional alternative to first_name and last_name.
email	string	Recommended. Existing contacts are updated by matching email.
phone	string	Optional phone number.
company_name	string	Optional company or business name.
segments	array\|string	Optional contact groups. Arrays are preferred; comma-separated strings are accepted.
tags	array\|string	Alias for segments.
source	string	Optional lead source. Defaults to api.
stage_type	string	Optional. Defaults to lead.
pipeline_key	string	Optional. Defaults to sales.

Success Response

{
  "success": true,
  "data": {
    "contact": {
      "id": 123,
      "first_name": "Dana",
      "last_name": "Pourjafar",
      "email": "lead@example.com",
      "phone": "+16045550123",
      "company_name": "Example Co",
      "stage_type": "lead",
      "pipeline_key": "sales",
      "created_at": "2026-04-21T16:00:00.000Z",
      "updated_at": "2026-04-21T16:00:00.000Z"
    },
    "upserted": false
  }
}