Customers

Customer Object

Customers are represented as JSON objects with the following properties

Name	Type	Description
id	integer	The ID of the customer.
name	string	The name of the customer.
owner	string	Slack/MS Teams User ID of the owner for the customer.
domains	string array	List of domain names associated with this customer.
channel_ids	string array	List of Slack channel IDs or MS Teams channel IDs associated with this customer.
revisit	boolean	Flag indicating if this customer requires revisiting.
portal_config	object	Configuration object for customer portal settings. Details about the object can be found here.
custom_field_values	object	An object containing custom field values. The object will have custom field IDs as keys and the values of the custom fields as values. Details about the object can be found here.
is_portal_available_to_all_users	boolean	Whether portal access is available to all users of this customer.
portal_allowed_user_emails	string array	List of email addresses that are allowed to access the customer portal.
collection_id	integer	Optional. The ID of the collection this customer belongs to.
external_system	string	Optional. External CRM system identifier (e.g., hubspot, salesforce). Null if not linked to external system.
external_entity_id	string	Optional. External CRM entity identifier. Null if not linked to external system.
external_deal_id	string	Optional. External CRM deal identifier. Null if not linked to external deal.
version	integer	Version number of the customer object, increments with each update. Used for optimistic locking.
created_at	string	The creation timestamp of the customer in ISO 8601 format.
updated_at	string	The last update timestamp of the customer in ISO 8601 format.

Portal Config Object

The portal_config is represented as a JSON object with the following properties

Name	Type	Description
enabled	boolean	Whether portal access is enabled for this customer.

Custom Field Values Object

The custom_field_values object contains custom field data for the customer. The object uses custom field IDs as keys and the corresponding field values as values.

Note: For select and multi_select type custom fields, the values are option IDs (strings), not the display text.

Custom Field Value Format Guide

The table below outlines the expected value formats for different custom field types:

Custom Field Type	Expected Value Format	Example Value
select	String (option ID)	"1"
multi_select	Array of strings (option IDs)	["1", "2"]
text	String	"Sample text"
number	Number	500000
date	String (ISO 8601 date format)	"2024-10-30"

Get All Customers

GET https://api.clearfeed.app/v1/rest/customers

Get all customers in an account with pagination support

Query Parameters

Name	Type	Description
before	string	Optional. Fetch records created before this timestamp (ISO 8601 format).
after	string	Optional. Fetch records created after this timestamp (ISO 8601 format).
sort_order	enum	Optional. Sort order for results. Can be asc or desc. Defaults to desc.
limit	integer	Optional. Number of results to return (1-100). Defaults to 50.
next_cursor	string	Optional. Base64-encoded cursor for pagination.

200

{
  "customers": [
    {
      "id": 123,
      "name": "Acme Corp",
      "owner": "U03AB1CD2EF",
      "domains": ["acme.com"],
      "channel_ids": ["C01ABC2DEF3", "C04GHI5JKL6"],
      "revisit": false,
      "portal_config": { "enabled": true },
      "custom_field_values": { "3011": "Enterprise", "3012": 500000 },
      "is_portal_available_to_all_users": true,
      "portal_allowed_user_emails": ["[email protected]"],
      "collection_id": 21,
      "external_system": null,
      "external_entity_id": null,
      "external_deal_id": null,
      "version": 0,
      "created_at": "2024-10-30T18:18:10.839Z",
      "updated_at": "2024-10-30T18:18:10.839Z"
    }
  ],
  "response_metadata": {
    "next_cursor": "MTI0",
    "count": 1
  }
}

403: Forbidden Permission denied

Search Customers

POST https://api.clearfeed.app/v1/rest/customers/search

Search customers with advanced filtering capabilities. Multiple filters are applied as AND conditions.

Request Body

Name	Type	Description
filters	array	Optional. Array of filter objects. See Filter Objects for details.
before	string	Optional. Fetch records created before this timestamp (ISO 8601 format).
after	string	Optional. Fetch records created after this timestamp (ISO 8601 format).
sort_order	enum	Optional. Sort order for results. Can be asc or desc. Defaults to desc.
limit	integer	Optional. Number of results to return (1-100). Defaults to 50.
next_cursor	string	Optional. Base64-encoded cursor for pagination.

Filter Objects

Domain Filter

Filter customers by domain names with array comparison operators.

Name	Type	Description
field	literal	Must be exactly: 'domains'
operator	enum	Array comparison operator. Options: - overlaps: Matches if any input domain exists in customer's domains - contains_all: Matches if customer's domains contain all input domains
values	string array	Array of domain names to filter by. Must be valid FQDNs (Fully Qualified Domain Names).

External Entity Filter

Filter customers by their external CRM system identifiers.

Name	Type	Description
field	literal	Must be exactly: 'external_entity'
entity_type	enum	External CRM system. Can be hubspot or salesforce.
entity_id	string	The external entity identifier from the CRM system (max 255 characters).

Example request body with domain filter:

{
  "filters": [
    {
      "field": "domains",
      "operator": "overlaps",
      "values": ["acme.com", "acme.io"]
    }
  ],
  "sort_order": "desc",
  "limit": 50
}

Example request body with external entity filter:

{
  "filters": [
    {
      "field": "external_entity",
      "entity_type": "hubspot",
      "entity_id": "12345678"
    }
  ],
  "limit": 50
}

Example request body with multiple filters (AND condition):

{
  "filters": [
    {
      "field": "domains",
      "operator": "overlaps",
      "values": ["acme.com"]
    },
    {
      "field": "external_entity",
      "entity_type": "hubspot",
      "entity_id": "12345678"
    }
  ],
  "before": "2025-11-11T10:00:00Z",
  "after": "2025-11-01T00:00:00Z",
  "sort_order": "desc",
  "limit": 50
}

200: Success

{
  "customers": [
    {
      "id": 123,
      "name": "Acme Corp",
      "owner": "U03AB1CD2EF",
      "domains": ["acme.com"],
      "channel_ids": ["C01ABC2DEF3", "C04GHI5JKL6"],
      "revisit": false,
      "portal_config": { "enabled": true },
      "custom_field_values": { "3011": "Enterprise", "3012": 500000 },
      "is_portal_available_to_all_users": true,
      "portal_allowed_user_emails": ["[email protected]"],
      "collection_id": 21,
      "external_system": null,
      "external_entity_id": null,
      "external_deal_id": null,
      "version": 0,
      "created_at": "2024-10-30T18:18:10.839Z",
      "updated_at": "2024-10-30T18:18:10.839Z"
    }
  ],
  "response_metadata": {
    "next_cursor": "MTI0",
    "count": 1
  }
}

400: Bad Request Invalid filter parameters

403: Forbidden Permission denied

Create Customer

POST https://api.clearfeed.app/v1/rest/customers

Create a new customer in your account.

Request Body

Name	Type	Description
name*	string	Name of the customer.
owner*	string	Slack/MS Teams User ID of the owner for the customer.
domains	string array	Optional. List of domain names associated with this customer.
channel_ids	string array	Optional. List of Slack channel IDs or MS Teams channel IDs to associate with this customer.
portal_config	object	Optional. Portal configuration object. Details about the object can be found here.
custom_field_values	object	Optional. An object containing custom field values. Details about the object can be found here.
is_portal_available_to_all_users	boolean	Optional. Whether portal access is available to all users of this customer.
portal_allowed_user_emails	string array	Optional. Email addresses allowed to access the customer portal.
collection_id	integer	Optional. The ID of the collection to assign this customer to.

Example request body:

{
  "name": "Acme Corp",
  "owner": "U03AB1CD2EF",
  "domains": ["acme.com"],
  "channel_ids": ["C01ABC2DEF3", "C04GHI5JKL6"],
  "portal_config": {
    "enabled": true
  },
  "custom_field_values": {
    "3011": "Enterprise",
    "3012": 500000
  },
  "is_portal_available_to_all_users": true,
  "portal_allowed_user_emails": ["[email protected]"],
  "collection_id": 21
}

201: Created

{
  "customer": {
    "id": 123,
    "name": "Acme Corp",
    "owner": "U03AB1CD2EF",
    "domains": ["acme.com"],
    "channel_ids": ["C01ABC2DEF3", "C04GHI5JKL6"],
    "revisit": false,
    "portal_config": { "enabled": true },
    "custom_field_values": { "3011": "Enterprise", "3012": 500000 },
    "is_portal_available_to_all_users": true,
    "portal_allowed_user_emails": ["[email protected]"],
    "collection_id": 21,
    "external_system": null,
    "external_entity_id": null,
    "external_deal_id": null,
    "version": 0,
    "created_at": "2024-10-30T18:18:10.839Z",
    "updated_at": "2024-10-30T18:18:10.839Z"
  }
}

400: Bad Request Invalid request body

403: Forbidden Permission denied

Get Customer by ID

GET https://api.clearfeed.app/v1/rest/customers/:id

Retrieve details of a specific customer by ID.

Path Parameters

Name	Type	Description
id*	integer	The ID of the customer to retrieve

200: Success

{
  "customer": {
    "id": 123,
    "name": "Acme Corp",
    "owner": "U03AB1CD2EF",
    "domains": ["acme.com"],
    "channel_ids": ["C01ABC2DEF3", "C04GHI5JKL6"],
    "revisit": false,
    "portal_config": { "enabled": true },
    "custom_field_values": { "3011": "Enterprise", "3012": 500000 },
    "is_portal_available_to_all_users": true,
    "portal_allowed_user_emails": ["[email protected]"],
    "collection_id": 21,
    "external_system": null,
    "external_entity_id": null,
    "external_deal_id": null,
    "version": 0,
    "created_at": "2024-10-30T18:18:10.839Z",
    "updated_at": "2024-10-30T18:18:10.839Z"
  }
}

403: Forbidden Permission denied

404: Not Found Customer not found

Update Customer

PATCH https://api.clearfeed.app/v1/rest/customers/:id

Update an existing customer. All fields are optional - only provided fields will be updated.

Path Parameters

Name	Type	Description
id*	integer	The ID of the customer to update

Request Body

Name	Type	Description
version*	integer	Current version number of the customer. Used for optimistic locking to prevent concurrent updates.
name	string	Optional. Name of the customer.
owner	string	Optional. Slack/MS Teams User ID of the owner for the customer.
domains	string array	Optional. List of domain names associated with this customer.
channel_ids	string array	Optional. List of Slack channel IDs or MS Teams channel IDs.
portal_config	object	Optional. Portal configuration object. Details about the object can be found here.
custom_field_values	object	Optional. An object containing custom field values. Set a field to null to clear its value. Details about the object can be found here.
is_portal_available_to_all_users	boolean	Optional. Whether portal access is available to all users.
portal_allowed_user_emails	string array	Optional. Email addresses allowed to access the customer portal.
collection_id	integer	Optional. The ID of the collection to assign this customer to.

Important: The version field is required to prevent concurrent updates. If the version doesn't match the current customer version, the update will fail with a 409 Conflict error. Retrieve the latest customer data and retry with the updated version number.

Example request body:

{
  "version": 0,
  "name": "Acme International",
  "domains": ["acme.com", "acme.io"],
  "owner": "U07XY8ZA9BC",
  "custom_field_values": {
    "3012": 1200000,
    "3013": null
  },
  "is_portal_available_to_all_users": false,
  "portal_allowed_user_emails": ["[email protected]"]
}

200: Success

{
  "customer": {
    "id": 123,
    "name": "Acme International",
    "owner": "U07XY8ZA9BC",
    "domains": ["acme.com", "acme.io"],
    "channel_ids": ["C01ABC2DEF3", "C04GHI5JKL6"],
    "revisit": false,
    "portal_config": { "enabled": true },
    "custom_field_values": { "3011": "Enterprise", "3012": 1200000 },
    "is_portal_available_to_all_users": false,
    "portal_allowed_user_emails": ["[email protected]"],
    "collection_id": 21,
    "external_system": null,
    "external_entity_id": null,
    "external_deal_id": null,
    "version": 1,
    "created_at": "2024-10-30T18:18:10.839Z",
    "updated_at": "2024-10-30T18:25:15.122Z"
  }
}

400: Bad Request Invalid request body

403: Forbidden Permission denied

404: Not Found Customer not found

409: Conflict Outdated version