Print Friendly, PDF & Email

The Broadstripes 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.

The API provides two kinds of data — a JSON array of specific attributes for a list of contacts matching the provided Broadstripes query text, or a simple count of the same contacts.

Prerequisites

To build an HTTP request (essentially, a URL) that can successfully invoke the API, you will need two unique identifiers:

  1. The Authentication Token specific to your user account.
  2. The ID for the project you’re working with. (API calls are project-specific, of course.)

Both of these can be obtained by clicking on your name in the upper right corner of the Broadstripes screen. Doing so will take you to the edit page for your user account’s settings. At the top of the page, you’ll see the two IDs with copy-to-clipboard icons next to them.

Retrieving contact details

The shell command below uses curl, a widely available tool that allows you to generate HTTP requests. This command will retrieve information in JSON form for people who are 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”
Let’s take a closer look at the this command and what each section means.
  • As mentioned above, the command starts by invoking curl, an open source command-line tool which we’re using here to make a GET request to a Broadstripes API endpoint.
  • curl -G -H “X-Broadstripes-Authentication-Token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”:
      • -G: This option tells curl to send the data as part of the URL query string with the GET method
      • -H stands for “header” and allows you to pass header information along with your request.
      • “X-Broadstripes-Authentication-Token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx” is the header being sent. The header (X-Broadstripes-Authentication-Token) is used to authenticate the request with the server. The value (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx) should of course be replaced by your user-specific API token.
  • -d “project_id=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy”  -d stands for “data”. It allows you to add data to the request. In this case, the data is the project id. This data will be included as a query parameter. The server will return contacts that belong to the project with this ID. You may obtain your project id on your edit page in the app. (Click on your name in the top right of the app.)
  • -d “q=employer%3d%22Acme%20Inc%22”   is a URL-encoded string that translates to q=employer=”Acme Inc”. It is a query parameter (q=) that searches for contacts who are employed by Acme Inc. You will perform queries as you would inside the app, using the Broadstripes search language (keywords, operators and values). For the search language to work in a URL, you must convert operators and special characters to URL-encoded string. You may use the table below as a guide for operator and special character conversion.
  • fields%5B%5D=name is a URL-encoded string that translates to fields[]=name. This that the request is asking for only the “name” fields of the contacts.
    In your API requests, you have the option to request data from various fields. Currently, you can request information 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  in the project must be entered exactly the  same as it is in the project including capital letters and spaces.  e.g. fields%5B%5D=Signed%20Card
  • “https://crm.broadstripes.com/api/contacts” is the URL to which the request is being sent. It contains the endpoint of the Broadstripes API where the contacts are being accessed.
Operator URL encoded operatorQuery exampleURL Encoded query
=%3Dfield=value field%3Dvalue
!=%21%3Dfield!=valuefield%21%3Dvalue
> %3Efield>value field%3Evalue
>=%3E%3Dfield>=value field%3E%3Dvalue
:%3Afield:valuefield%3Avalue
<%3Cfieldfield%3Cvalue
<=%3C%3Dfield<=valuefield%3C%3Dvalue
' ' (space)%20field=value1 OR field=value2field%3Dvalue1%20OR%20field%3Dvalue2

Retrieving contact counts

The curl statement to retrieve a count of records that match the conditions of your query will be very similar to the curl statement above. There are two main differences in the statement:

The following command will retrieve the count of people who are 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” \
“https://crm.broadstripes.com/api/contacts/count”
  • curl: This is the command-line tool used to initiate the transfer of data from the server. In this example, it is used to make a GET request to an API endpoint.
    • -G: This option tells curl to send the data as part of the URL query string with the GET method
    • -H “X-Broadstripes-Authentication-Token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx” :
    • -H stands for “header”. It allows you to pass additional header information along with your request.
    • “X-Broadstripes-Authentication-Token:” is the header being sent. This particular header (X-Broadstripes-Authentication-Token) is used to authenticate the request with the server. The value xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx is the token that grants access.
  • -d “project_id=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy”: -d stands for “data”. It allows you to add data to the request. In this case the data is the project id, project_id=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy. This data will be included as a query parameter in the URL.
  • -d “q=employer%3d%22Acme%20Inc%22” : This is another data field added to the request. This URL-encoded string translates to q=employer%3d%22Acme%20Inc%22. It is a query parameter (q=) that searches for contacts who are employed at Acme Inc. You will perform queries as you would inside the app, using the Broadstripes search language (keywords, operators and values). For the search language to work in a URL, you must convert operators and special characters to URL-encoded string. You may use the table above as a guide for operator conversion and special character conversion.
  • “https://groton.broadstripes.com/api/contacts/count”:This is the URL to which the request is being sent. It contains the endpoint of the Broadstripes API where the count of contacts is being accessed.

With the prerequisites and examples provided, you are now equipped to make effective API calls to access your project data within Broadstripes.