« Back to guides


The customers data api is used to retrieve up-to-date customer data from Custobar. The set of returned
customers may be filtered using query parameters.

To retrieve customer with external id CUSTOMERID, make a GET request to:


The result is always a JSON object with customers property, with all mathcing
customers as a list

    "customers": [
            "external_id": "CUSTOMERID",
            "first_name": "Customer",
            "last_name": "Samplesson",
            "email": "[email protected]",
            "can_email": true

If there are no matching customers, the customers list will be empty. For _externalid
queries there are always either zero or one matching customers.

To retrieve customers with email address, make a similar GET request:

https://COMPANY.custobar.com/api/data/customers/[email protected]

There might be several customers with the same email address, so this could return
more than one matching customer.

Any customer data field can be used for filtering. For example, to retrieve customers with last name Anderson having email permission, use:



By default, the data api returns maximum of 100 results. You can specify a custom maximum result set size
using the limit parameter, for example:


returns up to 1000 customers with email permission.

However, the maximum value for limit parameter is 10000 (100000 if using CSV, see format below). If there are more results that the limit allows, they can be delivered using multiple requests. In case there are more results available, the response includes additional next_url field. The next chunk of results may be retrieved from this url. To retrieve all results, you must keep requesting more results until the last response contains no next_url field. Here is an example in Python, retrieving all customers
in chunks of 500:

import requests

customers = []
url = 'https:COMPANY.custobar.com/api/data/customers/?limit=500'
while url:
    reply = requests.get(url).json()
    url = reply.get('next_url')

The next_url field is also available as the HTTP header field X-Custobar-Next-Url in the HTTP response.
This is useful when using CSV format, as there is no place for the next url in the response data.

Specifying returned fields

By default, the customers data api returns all data associated with matching customers.
If you are only interested in certain data fields, you can specify them as a comma-separated
list with fields query parameters:


_Externalid is always included, so this will return:

    "customers": [
            "external_id": "CUSTOMERID",
            "email": "[email protected]",
            "can_email": true

Note that if a customer does not have a particular data field, it is not included in the
result, even if the field was specified in fields parameter.


By default, the data api returns the matching customers as JSON. However, by specifying format parameter,
the results can be formatted as CSV (comma-separated-list).


retrieves a CSV of all customers with email permission.

If fields parameter is not specified, the returned CSV contains columns for all potential properties
in the data, many of which may not be in use in the particular set of customers. Thus it is good practice
to specify fields when requesting data in CSV.


Product data can be retrived just like customer data. For example, retrieve all products in category “books”: