Create Contact

curl --request POST \
  --url https://api.flowiq.live/contact \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "John Doe",
  "phone_number": "+27123456789",
  "email": "john@example.com",
  "tags": "customer,premium,vip"
}
'

{
  "success": true,
  "message": "Contact created successfully",
  "contact": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "full_name": "John Doe",
    "whatsapp_id": "27123456789",
    "phone_number": "+27123456789",
    "email": "john@example.com",
    "tags": [
      "customer",
      "premium",
      "vip"
    ],
    "organization_id": "org-uuid-here",
    "created_at": "2025-12-11T10:30:00Z"
  },
  "whatsapp_verified": true
}

POST

contact

curl --request POST \
  --url https://api.flowiq.live/contact \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "John Doe",
  "phone_number": "+27123456789",
  "email": "john@example.com",
  "tags": "customer,premium,vip"
}
'

{
  "success": true,
  "message": "Contact created successfully",
  "contact": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "full_name": "John Doe",
    "whatsapp_id": "27123456789",
    "phone_number": "+27123456789",
    "email": "john@example.com",
    "tags": [
      "customer",
      "premium",
      "vip"
    ],
    "organization_id": "org-uuid-here",
    "created_at": "2025-12-11T10:30:00Z"
  },
  "whatsapp_verified": true
}

This endpoint creates a new contact. FlowIQ checks whether the number is on WhatsApp; the check is advisory, so a contact is still created when the check can’t be completed (see whatsapp_verified).

Overview

Create a new contact in your FlowIQ organization. The API automatically:

Checks whether the phone number is on WhatsApp (rejects numbers confirmed not to be)
Normalizes phone numbers for consistent storage
Checks for duplicate contacts
Parses and stores contact tags

Authentication

All requests require a Bearer token with API key format (fiq_...) in the Authorization header:

Authorization: Bearer fiq_YOUR_API_KEY

Only API keys with the fiq_ prefix are accepted.

Basic Usage

Create a Contact

curl -X POST "https://api.flowiq.live/contact" \
  -H "Authorization: Bearer fiq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "phone_number": "+27123456789",
    "email": "john@example.com",
    "tags": "customer,premium,vip"
  }'

Minimal Request (Name + Phone)

curl -X POST "https://api.flowiq.live/contact" \
  -H "Authorization: Bearer fiq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "phone_number": "+27123456789"
  }'

Request Parameters

Request Body

Field	Type	Required	Description
`phone_number`	string	Yes	Phone number with country code (e.g., +27123456789)
`name`	string	Yes	Contact’s full name
`email`	string	No	Contact’s email address
`tags`	string	No	Comma-separated tags (e.g., “customer,premium,vip”)

Phone numbers are automatically cleaned and normalized. Both +27 12 345 6789 and 27123456789 will be stored consistently.

Response Examples

Success Response (201)

{
  "success": true,
  "message": "Contact created successfully",
  "contact": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "full_name": "John Doe",
    "whatsapp_id": "27123456789",
    "phone_number": "+27123456789",
    "email": "john@example.com",
    "tags": ["customer", "premium", "vip"],
    "organization_id": "org-uuid-here",
    "created_at": "2025-12-11T10:30:00Z"
  },
  "whatsapp_verified": true
}

whatsapp_verified is true when the number was confirmed on WhatsApp, or null when the check couldn’t be completed. A null contact is created normally; treat it as “not checked”, not as “not on WhatsApp”.

Error: Contact Already Exists (409)

{
  "error": "Contact already exists",
  "message": "A contact with this phone number already exists",
  "existing_contact": {
    "id": "existing-uuid",
    "full_name": "John Doe",
    "whatsapp_id": "27123456789"
  }
}

Error: Not on WhatsApp (400)

Returned only when the number is confirmed not to be on WhatsApp.

{
  "error": "Invalid WhatsApp number",
  "message": "The provided phone number is not registered on WhatsApp"
}

Error: Missing Phone Number (400)

{
  "error": "Missing required field",
  "message": "phone_number is required"
}

Error: Invalid API Key (401)

{
  "error": "Invalid API key",
  "message": "API key has been revoked"
}

Phone Number Validation

The API performs several validation steps:

Format Check: Removes special characters, keeps only digits
Length Check: Must be at least 10 digits (including country code)
WhatsApp Check: Asks whether the number is on WhatsApp. A number confirmed not to be on WhatsApp is rejected with a 400. If the check can’t be completed, the contact is created anyway and whatsapp_verified is null
Duplicate Check: Ensures no existing contact has the same WhatsApp ID in your organization

A 201 doesn’t guarantee the number is on WhatsApp. Check whatsapp_verified: only true means it was confirmed.

Tag Management

Tags can be provided as a comma-separated string and are automatically:

Split into individual tags
Trimmed of whitespace
Stored as a JSON array
Empty tags are filtered out

Example:

{
  "tags": "customer, premium, vip, "
}

Stored as:

{
  "tags": ["customer", "premium", "vip"]
}

Contact Properties

When a contact is created, the following properties are automatically set:

Property	Default Value	Description
`bot_status`	`true`	Bot is enabled for this contact
`archived`	`false`	Contact is not archived
`has_unread_messages`	`false`	No unread messages initially
`allow_broadcast`	`true`	Contact can receive broadcasts
`active_status`	`false`	Contact is not currently active
`blocked`	`false`	Contact is not blocked
`source.type`	`"api"`	Contact was created via API

Error Codes

Status Code	Error	Description
201	Success	Contact created successfully
400	Bad Request	Missing required fields, invalid phone number, or a number confirmed not to be on WhatsApp
401	Unauthorized	Invalid or expired API key
404	Not Found	Organization not found
409	Conflict	Contact with this phone number already exists
500	Internal Server Error	Server-side error occurred

Best Practices

Phone Number Format

Always include the country code (e.g., +27 for South Africa, +1 for USA/Canada). The API handles formatting automatically.

Duplicate Detection

Check the 409 error response to get details about the existing contact before attempting to update or create a new one.

Tags Organization

Use consistent tag naming (e.g., lowercase, no spaces) for easier filtering and organization.

Error Handling

Handle the 400 “Invalid WhatsApp number” response by asking the user to check the number, and treat whatsapp_verified: null as unconfirmed rather than invalid.

Integration Example

async function createContact(apiKey, contactData) {
  try {
    const response = await fetch(
      `https://api.flowiq.live/contact`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(contactData)
      }
    );

    const data = await response.json();

    if (!response.ok) {
      // Handle specific error cases
      if (response.status === 409) {
        console.log('Contact already exists:', data.existing_contact);
      } else if (response.status === 400) {
        console.error('Invalid data:', data.message);
      }
      throw new Error(data.message);
    }

    return data.contact;
  } catch (error) {
    console.error('Failed to create contact:', error);
    throw error;
  }
}

// Usage
const newContact = await createContact(
  'fiq_your_api_key',
  {
    name: 'Jane Smith',
    phone_number: '+27987654321',
    email: 'jane@example.com',
    tags: 'lead,website'
  }
);

Authorizations

Authorization

string

header

required

Your FlowIQ API key (from Settings → Profile → API Keys), sent as a bearer token. Format: Bearer fiq_YOUR_API_KEY

Body

application/json

name

string

required

Contact's full name

Example:

"John Doe"

phone_number

string

required

Phone number with country code (required)

Example:

"+27123456789"

string<email>

Contact's email address

Example:

"john@example.com"

Response

Contact created successfully

success

boolean

required

Whether the request was successful

Example:

true

message

string

required

Success message

Example:

"Contact created successfully"

contact

object

required

Show child attributes

whatsapp_verified

boolean | null

required

true when the number was confirmed on WhatsApp. null when verification could not be completed; the contact is still created. (A number confirmed NOT to be on WhatsApp returns 400 instead.)

Example:

true

Get Started

WhatsApp

Calling

Instagram

Messenger

Subscriptions

Webhooks

Reporting & AI

Key Features

Overview

Authentication

Basic Usage

Create a Contact

Minimal Request (Name + Phone)

Request Parameters

Request Body

Response Examples

Success Response (201)

Error: Contact Already Exists (409)

Error: Not on WhatsApp (400)

Error: Missing Phone Number (400)

Error: Invalid API Key (401)

Phone Number Validation

Tag Management

Contact Properties

Error Codes

Best Practices

Phone Number Format

Duplicate Detection

Tags Organization

Error Handling

Integration Example

Authorizations

Body

Response

​Overview

​Authentication

​Basic Usage

​Create a Contact

​Minimal Request (Name + Phone)

​Request Parameters

​Request Body

​Response Examples

​Success Response (201)

​Error: Contact Already Exists (409)

​Error: Not on WhatsApp (400)

​Error: Missing Phone Number (400)

​Error: Invalid API Key (401)

​Phone Number Validation

​Tag Management

​Contact Properties

​Error Codes

​Best Practices

Phone Number Format

Duplicate Detection

Tags Organization

Error Handling

​Integration Example

Authorizations

Body

Response

Overview

Authentication

Basic Usage

Create a Contact

Minimal Request (Name + Phone)

Request Parameters

Request Body

Response Examples

Success Response (201)

Error: Contact Already Exists (409)

Error: Not on WhatsApp (400)

Error: Missing Phone Number (400)

Error: Invalid API Key (401)

Phone Number Validation

Tag Management

Contact Properties

Error Codes

Best Practices

Integration Example