> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowapt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Contact
> Create a new contact with WhatsApp number verification. The phone number must be registered on WhatsApp and will be verified using FlowMod's verification service.
## Key Features
- Automatic WhatsApp number verification
- Phone number normalization
- Duplicate detection
- Tag parsing from comma-separated strings
- API key authentication with organization validation
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:
```bash theme={null}
Authorization: Bearer fiq_YOUR_API_KEY
```
Only API keys with the `fiq_` prefix are accepted.
***
## Basic Usage
### Create a Contact
```bash theme={null}
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)
```bash theme={null}
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)
```json theme={null}
{
"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)
```json theme={null}
{
"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)
```json theme={null}
{
"error": "Invalid WhatsApp number",
"message": "The provided phone number is not registered on WhatsApp"
}
```
### Error: Missing Phone Number (400)
```json theme={null}
{
"error": "Missing required field",
"message": "phone_number is required"
}
```
### Error: Invalid API Key (401)
```json theme={null}
{
"error": "Invalid API key",
"message": "API key has been revoked"
}
```
***
## Phone Number Validation
The API performs several validation steps:
1. **Format Check**: Removes special characters, keeps only digits
2. **Length Check**: Must be at least 10 digits (including country code)
3. **WhatsApp Verification**: Verifies the number is registered on WhatsApp using FlowMod's verification service
4. **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:**
```json theme={null}
{
"tags": "customer, premium, vip, "
}
```
**Stored as:**
```json theme={null}
{
"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
Always include the country code (e.g., +27 for South Africa, +1 for USA/Canada). The API handles formatting automatically.
Check the 409 error response to get details about the existing contact before attempting to update or create a new one.
Use consistent tag naming (e.g., lowercase, no spaces) for easier filtering and organization.
Always handle WhatsApp verification failures gracefully - inform users that the number must be registered on WhatsApp.
***
## Integration Example
```javascript theme={null}
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'
}
);
```
## OpenAPI
````yaml POST /contact
openapi: 3.1.0
info:
title: FlowIQ Conversations API
version: 1.0.0
description: >-
Complete WhatsApp Conversations API for retrieving messages, contacts, and
conversation history.
## Authentication
All endpoints require a Bearer token in the header:
```
Authorization: Bearer YOUR_BEARER_TOKEN
```
## Example API Call
```bash
curl -X GET
"https://api.flowiq.live/conversations?whatsappNumber=27123456789&limit=10"
\
-H "Authorization: Bearer YOUR_BEARER_TOKEN"
```
**Response:**
```json
{
"success": true,
"messages": [...],
"pagination": {
"currentPage": 1,
"totalPages": 5,
"hasNextPage": true
},
"count": 10
}
```
contact:
name: FlowIQ Support
email: dev@flowapt.com
servers:
- url: https://api.flowiq.live
description: FlowIQ Production API
security:
- BearerAuth: []
tags:
- name: Endpoints
description: Conversation and contact management API endpoints
- name: Webhooks
description: Webhook registration and management
paths:
/contact:
post:
tags:
- Endpoints
summary: Create Contact
description: >-
Create a new contact with WhatsApp number verification. The phone number
must be registered on WhatsApp and will be verified using FlowMod's
verification service.
## Key Features
- Automatic WhatsApp number verification
- Phone number normalization
- Duplicate detection
- Tag parsing from comma-separated strings
- API key authentication with organization validation
operationId: createContact
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateContactRequest'
examples:
full-contact:
summary: Complete Contact Information
value:
name: John Doe
phone_number: '+27123456789'
email: john@example.com
tags: customer,premium,vip
minimal-contact:
summary: Minimal Required Fields
value:
name: John Doe
phone_number: '+27123456789'
responses:
'201':
description: Contact created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CreateContactResponse'
example:
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'
'400':
description: Bad Request - Invalid or missing required fields
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missing-phone:
summary: Missing Phone Number
value:
error: Missing required field
message: phone_number is required
invalid-whatsapp:
summary: Invalid WhatsApp Number
value:
error: Invalid WhatsApp number
message: The provided phone number is not registered on WhatsApp
invalid-format:
summary: Invalid Phone Format
value:
error: Invalid phone number
message: >-
Phone number must include country code and be at least 10
digits
'401':
description: Unauthorized - Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalid-key:
summary: Invalid API Key
value:
error: Invalid API key
message: API key has been revoked
wrong-format:
summary: Wrong Token Format
value:
error: Invalid token format
message: Bearer token must be an API key (fiq_...)
auth-mismatch:
summary: Authentication Mismatch
value:
error: API key mismatch
message: API key does not belong to the specified organization
'404':
description: Not Found - Organization not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Organization not found
message: Organization not found for API key
'409':
description: Conflict - Contact already exists
content:
application/json:
schema:
$ref: '#/components/schemas/ContactExistsResponse'
example:
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'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal server error
message: Failed to create contact
security:
- BearerAuth: []
components:
schemas:
CreateContactRequest:
type: object
properties:
name:
type: string
description: Contact's full name
example: John Doe
phone_number:
type: string
description: Phone number with country code (required)
example: '+27123456789'
email:
type: string
format: email
description: Contact's email address
example: john@example.com
tags:
type: string
description: Comma-separated tags
example: customer,premium,vip
required:
- name
- phone_number
CreateContactResponse:
type: object
properties:
success:
type: boolean
description: Whether the request was successful
example: true
message:
type: string
description: Success message
example: Contact created successfully
contact:
type: object
properties:
id:
type: string
format: uuid
description: Contact unique identifier
example: 123e4567-e89b-12d3-a456-426614174000
full_name:
type: string
nullable: true
description: Contact full name
example: John Doe
whatsapp_id:
type: string
description: WhatsApp number (normalized, no special characters)
example: '27123456789'
phone_number:
type: string
description: Original phone number format
example: '+27123456789'
email:
type: string
nullable: true
format: email
description: Contact email address
example: john@example.com
tags:
type: array
items:
type: string
description: Contact tags
example:
- customer
- premium
- vip
organization_id:
type: string
format: uuid
description: Organization UUID
example: org-uuid-here
created_at:
type: string
format: date-time
description: Contact creation timestamp
example: '2025-12-11T10:30:00Z'
required:
- id
- whatsapp_id
- phone_number
- organization_id
- created_at
required:
- success
- message
- contact
ErrorResponse:
type: object
properties:
success:
type: boolean
description: Whether the request was successful
example: false
error:
type: string
description: Error message
example: Invalid or missing API key
message:
type: string
description: Detailed error message
example: Invalid or missing API key
details:
type: string
description: Additional error details (optional)
example: Shopify order not found
required:
- success
- error
ContactExistsResponse:
type: object
properties:
error:
type: string
description: Error message
example: Contact already exists
message:
type: string
description: Detailed error message
example: A contact with this phone number already exists
existing_contact:
type: object
properties:
id:
type: string
format: uuid
description: Existing contact ID
example: existing-uuid
full_name:
type: string
nullable: true
description: Existing contact name
example: John Doe
whatsapp_id:
type: string
description: Existing contact WhatsApp ID
example: '27123456789'
required:
- error
- message
- existing_contact
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 'Bearer token for authentication. Format: `Bearer YOUR_BEARER_TOKEN`'
bearerFormat: JWT
````