Contacts API

Manage your contacts programmatically. Create, update, list and delete contacts via the API.

Required permissions: readContacts for GET requests,writeContacts for POST, PUT, DELETE requests.

GET/api/v1/contacts

List all contacts with pagination and filtering

Query Parameters

page	Page number (default: 1)
limit	Items per page (default: 20, max: 100)
email	Filter by email (partial match)
tag	Filter by tag
unsubscribed	Filter by subscription status (true/false)

Example Request

curl -X GET "https://yourapp.com/api/v1/contacts?page=1&limit=20&tag=newsletter" \
  -H "Authorization: Bearer ntfn_your_api_key"

Response

{
  "success": true,
  "contacts": [
    {
      "id": "507f1f77bcf86cd799439011",
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "tags": ["newsletter", "customer"],
      "customFields": { "company": "Acme Inc" },
      "unsubscribed": false,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

POST/api/v1/contacts

Create a new contact

Request Body

email *	Contact email address
firstName	First name
lastName	Last name
tags	Array of tags
customFields	Object with custom field values

Example Request

curl -X POST "https://yourapp.com/api/v1/contacts" \
  -H "Authorization: Bearer ntfn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "tags": ["lead", "webinar"],
    "customFields": {
      "company": "Tech Corp",
      "source": "website"
    }
  }'

PUT/api/v1/contacts

Update an existing contact by ID or email

Request Body

id or email *	Contact identifier
firstName	Updated first name
lastName	Updated last name
tags	Replace all tags
customFields	Merge with existing custom fields

Example Request

curl -X PUT "https://yourapp.com/api/v1/contacts" \
  -H "Authorization: Bearer ntfn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "tags": ["customer", "premium"],
    "customFields": { "plan": "enterprise" }
  }'

DELETE/api/v1/contacts

Delete a contact by ID or email

Query Parameters

id or email *

Contact identifier

Example Request

curl -X DELETE "https://yourapp.com/api/v1/contacts?email=user@example.com" \
  -H "Authorization: Bearer ntfn_your_api_key"

Related Endpoints

Contact Lists →Send Email →

{ "success": true, "contacts": [ { "id": "507f1f77bcf86cd799439011", "email": "user@example.com", "firstName": "John", "lastName": "Doe", "tags": ["newsletter", "customer"], "customFields": { "company": "Acme Inc" }, "unsubscribed": false, "createdAt": "2024-01-15T10:30:00.000Z" } ], "pagination": { "page": 1, "limit": 20, "total": 150, "pages": 8 } }

curl -X POST "https://yourapp.com/api/v1/contacts" \ -H "Authorization: Bearer ntfn_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "email": "newuser@example.com", "firstName": "Jane", "lastName": "Smith", "tags": ["lead", "webinar"], "customFields": { "company": "Tech Corp", "source": "website" } }'

curl -X PUT "https://yourapp.com/api/v1/contacts" \ -H "Authorization: Bearer ntfn_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "email": "user@example.com", "tags": ["customer", "premium"], "customFields": { "plan": "enterprise" } }'