Skip to main content
The Broadstripes Search API allows you to retrieve data from a project via HTTP request, whether generated by a shell program such as curl or a scripting language.

​
Target Audience

Broadstripes users with Project Admin permissions.

​
API Overview

The API provides two kinds of data:
  • Contact Details: A JSON array of specific attributes for a list of contacts matching your Broadstripes query
  • Contact Counts: A simple count of contacts matching your query

​
Prerequisites

To make successful API calls, you need two unique identifiers:
  1. Authentication Token - Specific to your user account
  2. Project ID - The ID for the project you’re working with (API calls are project-specific)

​
Getting Your Credentials

Both identifiers can be obtained from the Broadstripes interface:
  1. Click the Settings dropdown in the upper right corner
  2. Choose “Your project settings”
  3. At the top of the page, you’ll see both IDs with copy-to-clipboard icons

​
Retrieving Contact Details

​
Basic Request Structure

Here’s a sample curl command that retrieves name data for people employed by “Acme Inc”: 
curl -G -H "X-Broadstripes-Authentication-Token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
-d "project_id=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" \
-d "q=employer%3d%22Acme%20Inc%22" \
-d "fields%5B%5D=name" \
"https://crm.broadstripes.com/api/contacts"

​
Request Parameters Explained

  • -G: Tells curl to send data as part of the URL query string with GET method
  • -H "X-Broadstripes-Authentication-Token": Authentication header with your API token
  • -d "project_id=...": Your project ID as a query parameter
  • -d "q=...": URL-encoded search query using Broadstripes search language
  • -d "fields[]=...": Specifies which fields to return in the response
  • API Endpoint: https://crm.broadstripes.com/api/contacts

​
Available Fields

You can request data from the following fields:
  • name: The name fields of the contact
  • events: Events associated with the contact
  • relationships: Information about the contact’s relationships
  • custom fields: Custom fields configured in your project. Field matching is case-insensitive.
    • Example: fields%5B%5D=Signed%20Card
  • external system IDs: External system values stored on contacts. Use the system’s key name, which follows the format: system name in lowercase, spaces replaced with underscores, followed by _id. Field matching is case-insensitive.

​
External system key name examples

External System NameKey Name for API
VANvan_id
Acme Systemacme_system_id
National Databasenational_database_id

​
Retrieving external system IDs

Here’s a sample curl command that retrieves name and VAN ID for people employed by “Acme Inc”: 
curl -G -H "X-Broadstripes-Authentication-Token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
-d "project_id=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" \
-d "q=employer%3d%22Acme%20Inc%22" \
-d "fields%5B%5D=name" \
-d "fields%5B%5D=van_id" \
"https://crm.broadstripes.com/api/contacts"
If a contact does not have a value for the requested external system, the field returns null in the response.

​
URL Encoding for Search Queries

When using Broadstripes search language in URLs, you must convert operators and special characters to URL-encoded strings:
OperatorURL EncodedQuery ExampleURL Encoded Query
=%3Dfield=valuefield%3Dvalue
!=%21%3Dfield!=valuefield%21%3Dvalue
>%3Efield>valuefield%3Evalue
>=%3E%3Dfield>=valuefield%3E%3Dvalue
:%3Afield:valuefield%3Avalue
<%3Cfield<valuefield%3Cvalue
<=%3C%3Dfield<=valuefield%3C%3Dvalue
(space)%20field=value1 OR field=value2field%3Dvalue1%20OR%20field%3Dvalue2

​
Retrieving Contact Counts

To get just the count of matching contacts, use a similar request with two key differences:
  1. No fields parameter needed - you’re only getting a count
  2. Different endpoint: Use /api/contacts/count instead of /api/contacts

​
Count Request Example

curl -G -H "X-Broadstripes-Authentication-Token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
-d "project_id=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" \
-d "q=employer%3d%22Acme%20Inc%22" \
"https://crm.broadstripes.com/api/contacts/count"

​
Getting Started

With these prerequisites and examples, you’re equipped to make effective API calls to access your project data within Broadstripes. Start by testing your authentication credentials and gradually build more complex queries using the Broadstripes search language.