Contacts API

Create and delete contacts via the API.

Create or Update Contact

Creates a new contact or updates an existing one if the email already exists.

POST /api/v1/contacts

Request Body

Field	Type	Required	Description
email	string	Yes	Email address (used as identifier)
externalId	string	No	Your unique identifier (defaults to email if not provided)
name	string	No	Display name
phone	string	No	Phone number
avatarUrl	string	No	Profile image URL
role	string	No	User role (e.g., "admin", "member")
plan	string	No	Subscription plan
signedUpAt	string	No	ISO 8601 date when user signed up
customAttributes	object	No	Custom attributes

Example Request

curl -X POST https://app.cueflow.so/api/v1/contacts \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "externalId": "user-123",
    "name": "Jane Smith",
    "plan": "pro",
    "role": "admin",
    "signedUpAt": "2024-01-15T10:30:00Z",
    "customAttributes": {
      "company": "Acme Inc",
      "teamSize": 50,
      "isEnterprise": true
    }
  }'

Response

{
  "success": true,
  "contact": {
    "id": "clx123abc...",
    "externalId": "user-123",
    "email": "[email protected]",
    "name": "Jane Smith",
    "plan": "pro",
    "role": "admin",
    "signedUpAt": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-12-13T15:30:00.000Z",
    "updatedAt": "2024-12-13T15:30:00.000Z"
  }
}

Status Codes

Code	Description
201	Contact created
200	Contact updated (already existed)
400	Invalid request body
401	Unauthorized

---

Delete Contact

Permanently delete a contact and all associated data.

DELETE /api/v1/contacts/:identifier

Path Parameters

Parameter	Description
identifier	Email address or externalId of the contact

Example Request

# Delete by email
curl -X DELETE https://app.cueflow.so/api/v1/contacts/[email protected] \
  -H "Authorization: Bearer sk_your_api_key"

# Delete by externalId
curl -X DELETE https://app.cueflow.so/api/v1/contacts/user-123 \
  -H "Authorization: Bearer sk_your_api_key"

Response

{
  "success": true,
  "deletedId": "clx123abc..."
}

Status Codes

Code	Description
200	Contact deleted
401	Unauthorized
404	Contact not found

Deleting a contact removes all associated data including events, message interactions, and feedback responses. This action cannot be undone.

---

Custom Attributes

Custom attributes allow you to store any additional data about your contacts.

Setting Attributes

Include attributes in the customAttributes object:

{
  "email": "[email protected]",
  "customAttributes": {
    "company": "Acme Inc",
    "teamSize": 50,
    "isEnterprise": true,
    "industry": "technology"
  }
}

Attribute Types

Type	Example
Text	"company": "Acme Inc"
Number	"teamSize": 50
Boolean	"isEnterprise": true

Custom attributes must be pre-defined in your workspace's Data > Attributes settings before they can be used.

---

Code Examples

Node.js

const axios = require('axios');

const cueflow = axios.create({
  baseURL: 'https://app.cueflow.so/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.CUEFLOW_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// Create or update contact
async function upsertContact(user) {
  const response = await cueflow.post('/contacts', {
    email: user.email,
    externalId: user.id,
    name: user.name,
    plan: user.subscription.plan
  });
  return response.data;
}

// Delete contact
async function deleteContact(identifier) {
  const response = await cueflow.delete(`/contacts/${encodeURIComponent(identifier)}`);
  return response.data;
}

Python

import requests
import os
from urllib.parse import quote

API_KEY = os.environ.get('CUEFLOW_API_KEY')
BASE_URL = 'https://app.cueflow.so/api/v1'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

def upsert_contact(user):
    response = requests.post(
        f'{BASE_URL}/contacts',
        headers=headers,
        json={
            'email': user['email'],
            'externalId': user['id'],
            'name': user['name'],
            'plan': user['plan']
        }
    )
    return response.json()

def delete_contact(identifier):
    response = requests.delete(
        f'{BASE_URL}/contacts/{quote(identifier)}',
        headers=headers
    )
    return response.json()

PHP

<?php

$apiKey = getenv('CUEFLOW_API_KEY');
$baseUrl = 'https://app.cueflow.so/api/v1';

function upsertContact($user) {
    global $apiKey, $baseUrl;

    $ch = curl_init("$baseUrl/contacts");
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $apiKey",
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
        'email' => $user['email'],
        'externalId' => $user['id'],
        'name' => $user['name'],
        'plan' => $user['plan']
    ]));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

function deleteContact($identifier) {
    global $apiKey, $baseUrl;

    $ch = curl_init("$baseUrl/contacts/" . urlencode($identifier));
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $apiKey"
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}