FluentCRM Developers

# Contacts

The Contacts API allows you to manage subscriber data in FluentCRM. You can create, read, update, and delete contacts, as well as manage their lists, tags, and custom field values.

# Contact Object

A contact represents a subscriber in your FluentCRM database.

# Properties

Property Type Description
id integer Unique identifier for the contact
user_id integer WordPress user ID (if linked)
hash string Unique hash for the contact
email string Email address (required, unique)
first_name string Contact's first name
last_name string Contact's last name
full_name string Combined first and last name
status string Subscription status
contact_type string Type of contact (lead, customer, etc.)
phone string Phone number
address_line_1 string Address line 1
address_line_2 string Address line 2
city string City
state string State/Province
country string Country code
postal_code string ZIP/Postal code
date_of_birth string Date of birth (YYYY-MM-DD)
photo string Gravatar photo URL
tags array Associated tags
lists array Associated lists
custom_values object Custom field values
created_at string Creation timestamp
updated_at string Last update timestamp

# Status Values

  • subscribed - Active subscriber
  • unsubscribed - Unsubscribed from emails
  • pending - Pending confirmation
  • transactional - Transactional emails only
  • bounced - Email bounced
  • complained - Failed but not bounced or spammed
  • spammed - Marked as spam by user

# List All Contacts

Retrieve a paginated list of contacts.

HTTP Request

GET /wp-json/fluent-crm/v2/subscribers
1

# Parameters

Parameter Type Default Description
per_page integer 10 Number of contacts per page
page integer 1 Page number for pagination
search string - Search contacts by name/email
filter_type string simple Filter by contact type (simple, advanced)
tags array - Filter by tag IDs
lists array - Filter by list IDs
statuses array - Filter by status values
sort_by string id Sort field (id, email, created_at)
sort_type string DESC Sort direction (ASC, DESC)
custom_fields boolean false Include custom field values
company_ids array - Filter by company IDs

# Example Request

curl "https://yourdomain.com/wp-json/fluent-crm/v2/subscribers?per_page=5&search=john" \
  -H "Authorization: Basic API_USERNAME:API_PASSWORD"
1
2

# Example Response

{
  "current_page": 1,
  "per_page": 5,
  "total": 150,
  "last_page": 30,
  "data": [
    {
      "id": "1",
      "user_id": "12",
      "hash": "abc123def456",
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "status": "subscribed",
      "contact_type": "lead",
      "phone": "+1-555-0123",
      "created_at": "2023-01-15 10:30:00",
      "updated_at": "2023-02-01 14:20:00",
      "photo": "https://www.gravatar.com/avatar/abc123?s=128",
      "tags": [
        {
          "id": "1",
          "title": "Newsletter",
          "slug": "newsletter"
        }
      ],
      "lists": [
        {
          "id": "2", 
          "title": "Customers",
          "slug": "customers"
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# Get a Specific Contact

Retrieve a single contact by ID or email.

HTTP Request

GET /wp-json/fluent-crm/v2/subscribers/{id}
GET /wp-json/fluent-crm/v2/subscribers/0?get_by_email={email}
1
2

# Parameters

Parameter Type Default Description
with array tags, lists, companies(if module enabled) Additional data to include

Available with options:

  • stats - Email statistics (opens, clicks)
  • custom_fields - Custom field definitions
  • subscriber.custom_values - Custom field values
  • commerce_stat - E-commerce statistics
  • companies - Associated companies

# Example Request

curl "https://yourdomain.com/wp-json/fluent-crm/v2/subscribers/1?with[]=stats&with[]=custom_values" \
  -H "Authorization: Basic API_USERNAME:API_PASSWORD"
1
2

# Example Response

{
  "subscriber": {
    "id": "1",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "status": "subscribed",
    "stats": {
      "emails": 25,
      "opens": 18,
      "clicks": 5
    },
    "custom_values": {
      "company": "Acme Corp",
      "industry": "Technology"
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Create a Contact

Add a new contact to FluentCRM.

HTTP Request

POST /wp-json/fluent-crm/v2/subscribers
1

# Parameters

Parameter Type Required Description
email string Yes Contact's email address
first_name string No First name
last_name string No Last name
status string Yes Subscription status
phone string No Phone number
date_of_birth string No Date of birth (YYYY-MM-DD)
address_line_1 string No Address line 1
address_line_2 string No Address line 2
city string No City
state string No State/Province
country string No Country
postal_code string No ZIP/Postal code
tags array No Tag IDs to assign
lists array No List IDs to assign
custom_values object No Custom field values
__force_update boolean No Update if contact exists

# Example Request

curl "https://yourdomain.com/wp-json/fluent-crm/v2/subscribers" \
  -H "Authorization: Basic API_USERNAME:API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith", 
    "email": "jane@example.com",
    "status": "subscribed",
    "phone": "+1-555-0124",
    "tags": [1, 2],
    "lists": [1],
    "custom_values": {
      "company": "Tech Solutions",
      "industry": "Software"
    }
  }'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Example Response

{
  "message": "Successfully added the subscriber.",
  "contact": {
    "id": 25,
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "status": "subscribed",
    "created_at": "2023-03-15 09:30:00",
    "tags": [
      {
        "id": "1",
        "title": "Newsletter"
      }
    ],
    "lists": [
      {
        "id": "1", 
        "title": "General"
      }
    ]
  },
  "action_type": "created"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# Update a Contact

Modify an existing contact's information.

HTTP Request

PUT /wp-json/fluent-crm/v2/subscribers/{id}
1

# Parameters

All create parameters are available, plus:

Parameter Type Description
attach_tags array Tags to add
detach_tags array Tags to remove
attach_lists array Lists to add
detach_lists array Lists to remove
custom_values object Custom field values to update

# Example Request

curl "https://yourdomain.com/wp-json/fluent-crm/v2/subscribers/1" \
  -X PUT \
  -H "Authorization: Basic API_USERNAME:API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "first_name": "John Updated",
      "attach_tags": [3],
      "detach_tags": [1],
      "custom_values": {
        "custom_field_slug_1": "custom_field_value",
        "custom_field_slug_2": "custom_field_value_2"
      },
    }
  }'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# Example Response

{
  "message": "Subscriber successfully updated",
  "contact": {
    "id": "1",
    "first_name": "John Updated",
    "email": "john@example.com"
  },
  "isDirty": true
}
1
2
3
4
5
6
7
8
9

# Create or Update Contact

Create a new contact or update existing one based on email.

HTTP Request

POST /wp-json/fluent-crm/v2/subscribers
1

# Parameters

Include __force_update: "yes" to enable upsert behavior.

# Example Request

curl "https://yourdomain.com/wp-json/fluent-crm/v2/subscribers" \
  -H "Authorization: Basic API_USERNAME:API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "__force_update": "yes",
    "email": "existing@example.com",
    "first_name": "Updated Name",
    "tags": [1, 2, 3]
  }'
1
2
3
4
5
6
7
8
9

# Delete a Contact

Remove a contact from FluentCRM.

HTTP Request

DELETE /wp-json/fluent-crm/v2/subscribers/{id}
1

# Example Request

curl "https://yourdomain.com/wp-json/fluent-crm/v2/subscribers/1" \
  -X DELETE \
  -H "Authorization: Basic API_USERNAME:API_PASSWORD"
1
2
3

# Example Response

{
  "message": "Selected Subscribers has been deleted"
}
1
2
3

# Working with Custom Fields

Custom fields allow you to store additional information about contacts.

# Setting Custom Field Values

curl "https://yourdomain.com/wp-json/fluent-crm/v2/subscribers" \
  -H "Authorization: Basic API_USERNAME:API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "status": "subscribed",
    "custom_values": {
      "company_size": "50-100",
      "interests": ["marketing", "sales"],
      "annual_revenue": "500000"
    }
  }'
1
2
3
4
5
6
7
8
9
10
11
12

# Retrieving Custom Field Values

curl "https://yourdomain.com/wp-json/fluent-crm/v2/subscribers/1?with[]=subscriber.custom_values" \
  -H "Authorization: Basic API_USERNAME:API_PASSWORD"
1
2

# Working with Notes

FluentCRM also provides a feature to add custom notes for contacts. There are 15 types of Contact Notes available to be added.

# Creating a new Note

HTTP Request

POST /wp-json/fluent-crm/v2/subscribers/{id}/notes
1

Parameters

Parameter Type Required Description
note object Yes note values
note.title String Yes note title
note.description Text Yes note description
note.type String Yes note type
note.created_at TimeDate Yes note created_at

Type Values

  • note - Note
  • call - Call
  • email - Email
  • meeting - Meeting
  • quote_sent - Quote Sent
  • quote_accepted - Quote Accepted
  • quote_refused - Quote Refused
  • invoice_sent - Invoice Sent
  • invoice_part_paid - Invoice Part Paid
  • invoice_paid - Invoice Paid
  • invoice_refunded - Invoice Refunded
  • transaction - Transaction
  • feedback - Feedback
  • tweet - Tweet
  • facebook_post - Facebook Post

Example Request

curl "https://yourdomain.com/wp-json/fluent-crm/v2/subscribers/1/notes" \
  -H "Authorization: Basic API_USERNAME:API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "note": {
      "title": "New Note",
      "description": "<p>very important note</p>",
      "type": "note",
      "created_at": "2025-08-10 12:00:00"
    }
  }'
1
2
3
4
5
6
7
8
9
10
11

Example Response

{
    "note": {
        "id": 47,
        "subscriber_id": "111",
        "parent_id": null,
        "created_by": "1",
        "status": "open",
        "type": "note",
        "is_private": "1",
        "title": "New Note",
        "description": "<p>very important note<\/p>",
        "created_at": "2025-08-10 12:00:00",
        "updated_at": "2025-08-07 12:13:02"
    },
    "message": "Note successfully updated"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Updating a Note

HTTP Request

PUT /wp-json/fluent-crm/v2/subscribers/{id}/notes/{id}
1

Example Request

curl "https://yourdomain.com/wp-json/fluent-crm/v2/subscribers/10/notes/11" \
  -X PUT \
  -H "Authorization: Basic API_USERNAME:API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "note": {
      "title": "New Note updated",
      "description": "<p>very important note</p>",
      "type": "note",
      "created_at": "2025-08-10 12:00:00"
    }
  }'
1
2
3
4
5
6
7
8
9
10
11
12

Example Response

{
    "note": {
        "id": 11,
        "subscriber_id": "10",
        "parent_id": null,
        "created_by": "1",
        "status": "open",
        "type": "note",
        "is_private": "1",
        "title": "New Note updated",
        "description": "<p>very important note<\/p>",
        "created_at": "2025-08-10 12:00:00",
        "updated_at": "2025-08-07 12:13:02"
    },
    "message": "Note successfully updated"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Retrieving notes of a contact

To retrieve all paginated notes for a specific contact, use the following endpoint:

Parameters

Parameter Type Default Description
per_page integer 10 Number of notes per page
page integer 1 Page number for pagination
search string - Search note by title

HTTP Request

GET /wp-json/fluent-crm/v2/subscribers/{id}/notes
1

Example Request

curl "https://yourdomain.com/wp-json/fluent-crm/v2/subscribers/1/notes?per_page=10&page=1&search=" \
-H "Authorization: Basic API_USERNAME:API_PASSWORD"
1
2

Example Response

{
    "notes": {
        "current_page": 1,
        "per_page": 10,
        "total": 5,
        "last_page": 1,
        "data": [
            {
                "added_by": {
                    "ID": 1,
                    "display_name": "Sheikh Hasib",
                    "first_name": "Sheikh",
                    "last_name": "Hasib"
                },
                "id": 47,
                "subscriber_id": "111",
                "created_by": "1",
                "status": "open",
                "type": "note",
                "title": "New Note",
                "description": "<p>very important note</p>",
                "is_private": "1",
                "parent_id": null,
                "created_at": "2025-08-10 12:00:00",
                "updated_at": "2025-08-07 12:13:02"
            }
        ]
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# Bulk Operations

# Bulk Update Example

To update multiple contacts, use individual PUT requests or create a batch script:

# Parameters

Parameter Type Required Description
action_name string Yes Bulk action name
subscriber_ids array Yes list of subscriber ids
new_status string No new status of contacts
# Update multiple contacts with the same data
curl "https://yourdomain.com/wp-json/fluent-crm/v2/subscribers/do-bulk-action" \
-X PUT \
-H "Authorization: Basic API_USERNAME:API_PASSWORD" \
-H "Content-Type: application/json" \
-d '{
    "action_name": "add_to_tags",
    "action_options": [9],
    "subscriber_ids": [1, 2, 3, 4, 5]
  }
'
1
2
3
4
5
6
7
8
9
10
11

Available action_name options:

  • add_to_tags - To add tags to contacts
  • add_to_lists - To add lists to contacts
  • remove_from_tags - To remove tags from contacts
  • remove_from_lists - To remove lists from contacts
  • change_contact_status - Change contact status
  • change_contact_type - Change contact type
  • add_to_email_sequence - Add contacts to email sequence
  • add_to_automation - Associate contacts to automation
  • send_double_optin - Send double opt-in email
  • update_custom_fields - Update custom fields of contacts
  • delete_contacts - Delete contacts
  • add_to_company - Add contacts to company
  • remove_from_company - Remove contacts from company

Available new_status options:

action_name Possible new_status value
change_contact_status subscribed, unsubscribed, pending, transactional, bounced, complained, complained, spammed
change_contact_type lead, customer
add_to_email_sequence sequence_id (integer) - ID of the email sequence
add_to_automation automation_id (integer) - ID of the automation
add_to_company company_id (integer) - ID of the company
remove_from_company company_id (integer) - ID of the company

Other parameters when action_name is update_custom_fields

Parameter Required Description
custom_field.key Yes Custom field slug
custom_field.type Yes Custom field type
custom_field.value Yes Custom field value

Available custom_field.type options:

  • text
  • textarea
  • number
  • select-multi
  • radio
  • checkbox
  • date
  • date_time

# Error Handling

Common error responses:

# Contact Not Found (404)

{
  "code": "rest_post_invalid_id",
  "message": "Invalid post ID.",
  "data": {"status": 404}
}
1
2
3
4
5

# Invalid Email (400)

{
  "code": "rest_invalid_param", 
  "message": "Invalid parameter: email",
  "data": {"status": 400}
}
1
2
3
4
5

# Duplicate Email (409)

{
  "message": "Contact already exists with this email",
  "data": {"status": 409}
}
1
2
3
4

# Best Practices

  1. Always validate emails before creating contacts
  2. Use pagination for large datasets
  3. Handle rate limits with proper retry logic
  4. Batch operations when updating multiple contacts
  5. Monitor status changes to maintain list hygiene
  6. Use webhooks for real-time synchronization
  • Lists - Organize contacts into lists
  • Tags - Categorize contacts with tags
  • Custom Fields - Manage custom contact data
  • Companies - Associate contacts with companies

← Lists →