Create Contact - FlowIQ API Documentation

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"
  }
}

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"
  }
}

This endpoint creates a new contact with WhatsApp number verification. The phone number must be registered on WhatsApp.

Overview

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

Verifies the phone number is registered on WhatsApp
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"
  }
}

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: Invalid WhatsApp Number (400)

{
  "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 Verification: Verifies the number is registered on WhatsApp using FlowMod’s verification service
Duplicate Check: Ensures no existing contact has the same WhatsApp ID in your organization

If the phone number is not registered on WhatsApp, the contact creation will fail with a 400 error.

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 or invalid phone number
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

Always handle WhatsApp verification failures gracefully - inform users that the number must be registered on WhatsApp.

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

Bearer token for authentication. Format: Bearer YOUR_BEARER_TOKEN

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

Get Contact Send Text Message

Documentation Index

​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: Invalid WhatsApp Number (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: Invalid WhatsApp Number (400)

Error: Missing Phone Number (400)

Error: Invalid API Key (401)

Phone Number Validation

Tag Management

Contact Properties

Error Codes

Best Practices

Integration Example