List Customers

Returns a list of all customer objects in your ChartMogul account.

Examples
curl -X GET "https://api.chartmogul.com/v1/customers?per_page=50" \
     -u YOUR_API_KEY:
ChartMogul::Customer.all(page: 1, per_page: 50)
ChartMogul.Customer.all(config, {
   per_page: 50
   }, function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Customer::all([
    'per_page' => 50
]);
?>
api.ListCustomers(&cm.ListCustomersParams{Cursor: cm.Cursor{PerPage: 2}})
chartmogul.Customer.all(config, per_page=2)
Result Format
{
  "entries":[
    {
      "id": 25647,
      "uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
      "external_id": "34916129",
      "external_ids": ["34916129"],
      "data_source_uuid": "ds_610b7a84-c50f-11e6-8aab-97d6db98913a",
      "data_source_uuids": ["ds_610b7a84-c50f-11e6-8aab-97d6db98913a"],
      "name": "Example Company",
      "company": "",
      "email": "[email protected]",
      "status": "Active",
      "lead_created_at": "2015-01-01T10:00:00-04:00",
      "free_trial_started_at": "2015-01-09T10:00:00-04:00",
      "customer-since": "2015-06-09T13:16:00-04:00",
      "city": "Nowhereville",
      "state": "Alaska",
      "country": "US",
      "zip": "0185128",
      "attributes":{
        "tags": ["engage", "unit loss", "discountable"],
        "stripe":{
          "uid": 7,
          "coupon": true
        },
        "clearbit":{
          "company":{
            "name": "Example Company",
            "legalName": "Example Company Inc.",
            "domain": "examplecompany.com",
            "url": "http://examplecompany.com",
            "category":{
              "sector": "Information Technology",
              "industryGroup": "Software and Services",
              "industry": "Software",
              "subIndustry": "Application Software"
            },
            "metrics":{
              "raised": 1502450000,
              "employees": 1000,
              "googleRank": 7,
              "alexaGlobalRank": 2319,
              "marketCap": null
            },
          },
          "person":{
            "name":{
              "fullName": "Bob Kramer"
            },
            "employment":{
              "name": "Example Company"
            }
          }
        },
        "custom":{
          "CAC": 213,
          "utmCampaign": "social media 1",
          "convertedAt": "2015-09-08 00:00:00",
          "pro": false,
          "salesRep": "Gabi"
        }
      },
      "address":{
        "address_zip": "0185128",
        "city": "Nowhereville",
        "country": "US",
        "state": "Alaska"
      },
      "mrr": 3000,
      "arr": 36000,
      "billing-system-url": "https:\/\/dashboard.stripe.com\/customers\/cus_4Z2ZpyJFuQ0XMb",
      "chartmogul-url": "https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company",
      "billing-system-type": "Stripe",
      "currency": "USD",
      "currency-sign": "$"
    },
    {"...49 more...": "...entries..."}
  ],
  "has_more": true,
  "per_page": 50,
  "page": 1,
  "current_page": 1,
  "total_pages": 4
}
#<ChartMogul::Customers:0x007fe7e09ca7c8 
@entries=[
  #<ChartMogul::Customer:0x007fe7e09ca408 
  @id=21064118, 
  @uuid="cus_2f9cfa3f-92d3-4801-9c9e-315fc2b61121", 
  @external_id="cus_0001", 
  @name="Adam Smith", 
  @email="[email protected]", 
  @status="Active", 
  @customer_since=2015-11-01 03:00:00 +0300, 
  @attributes={:tags=>[], :custom=>{}}, 
  @address={:country=>"United States", :state=>nil, :city=>"New York", :address_line1=>nil, :address_line2=>nil, :address_zip=>""}, 
  @mrr=4100, 
  @arr=49200, 
  @billing_system_url=nil, 
  @chartmogul_url="https://app.chartmogul.com/#customers/21064118-Adam_Smith", 
  @billing_system_type="Custom", 
  @currency="USD", 
  @currency_sign="$"
  >,
  # ... 49 more entries here ...
], 
@has_more=false, 
@per_page=50, 
@page=1
>
{
  "entries":[
    {
      "id": 25647,
      "uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
      "external_id": "34916129",
      "name": "Example Company",
      "email": "[email protected]",
      "status": "Active",
      "customer-since": "2015-06-09T13:16:00-04:00",
      "attributes":{
        "tags": ["engage", "unit loss", "discountable"],
        "stripe":{
          "uid": 7,
          "coupon": true
        },
        "clearbit":{
            "company":{
            "name": "Example Company",
            "legalName": "Example Company Inc.",
            "domain": "examplecompany.com",
            "url": "http://examplecompany.com",
            "category":{
              "sector": "Information Technology",
              "industryGroup": "Software and Services",
              "industry": "Software",
              "subIndustry": "Application Software"
            },
            "metrics":{
              "raised": 1502450000,
              "employees": 1000,
              "googleRank": 7,
              "alexaGlobalRank": 2319,
              "marketCap": null
            },
          },
          "person":{
            "name":{
              "fullName": "Bob Kramer"
            },
            "employment":{
              "name": "Example Company"
            }
          }
        },
        "custom":{
          "CAC": 213,
          "utmCampaign": "social media 1",
          "convertedAt": "2015-09-08 00:00:00",
          "pro": false,
          "salesRep": "Gabi"
        }
      },
      "address":{
        "address_line1": "First line of address",
        "address_line2": "Second line of address",
        "address_zip": "0185128",
        "city": "Nowhereville",
        "country": "US",
        "state": "Alaska"
      },
      "mrr": 3000,
      "arr": 36000,
      "billing-system-url": "https:\/\/dashboard.stripe.com\/customers\/cus_4Z2ZpyJFuQ0XMb",
      "chartmogul-url": "https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company",
      "billing-system-type": "Stripe",
      "currency": "USD",
      "currency-sign": "$"
    },
    {"...49 more...": "...entries..."}
  ],
  "has_more": true,
  "per_page": 50,
  "page": 1
}
<?php
ChartMogul\Customers::__set_state(array(
    "current_page" => 1,
    "total_pages" => 3,
    "has_more" => true,
    "per_page" => 50,
    "page" => 1,
    "entries" =>
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" =>
    array (
      0 =>
      ChartMogul\Customer::__set_state(array(
         "id" => 25647,
         "uuid" => "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
         "external_id" => "34916129",
         "name" => "Example Company",
         "email" => "[email protected]",
         "status" => "Active",
         "customer_since" => "2015-06-09T13:16:00-04:00",
         "attributes" =>
        array (
          "custom" =>
          array (
            "CAC" => 213,
            "utmCampaign" => "social media 1",
            "convertedAt" => "2015-09-08 00 =>00 =>00",
            "pro" => false,
            "salesRep" => "Gabi"
          ),
          "clearbit" =>
          array (
            "id" => "027b0d40-016c-40ea-8925-a076fa640992",
            "name" => "Acme",
            "legalName" => "Acme Inc.",
            "domain" => "acme.com",
            "url" => "http =>//acme.com",
            "metrics" => array (
              "raised" => 1502450000,
              "employees" => 1000,
              "googleRank" => 7,
              "alexaGlobalRank" => 2319,
              "marketCap" => null
            ),
            "category" => array (
              "sector" => "Information Technology",
              "industryGroup" => "Software and Services",
              "industry" => "Software",
              "subIndustry" => "Application Software"
            )
          ),
          "stripe" =>
          array (
            "uid" => 7,
            "coupon" => true
          ),
          "tags" =>
          array (
            0 => "engage",
            1 => "unit loss",
            2 => "discountable"
          ),
        ),
         "address" =>
        array (
          "address_line1" => "First line of address",
          "address_line2" => "Second line of address",
          "address_zip" => "0185128",
          "city" => "Nowhereville",
          "state" => "Alaska",
          "country" => "US"
        ),
         "mrr" => 3000,
         "arr" => 36000,
         "billing_system_url" => "https:\/\/dashboard.stripe.com\/customers\/cus_4Z2ZpyJFuQ0XMb",
         "chartmogul_url" => "https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company",
         "billing_system_type" => "Stripe",
         "currency" => "USD",
         "currency_sign" => "$",
         "data_source_uuid" => "ds_80686670-cc45-11e6-b9da-ff67b9895fe3",
         "data_source_uuids" =>
        array (
          0 => "ds_80686670-cc45-11e6-b9da-ff67b9895fe3",
        ),
         "external_ids" =>
        array (
          0 => "cus_0001",
        ),
         "city" => "Nowhereville",
         "country" => "US",
         "state" => "Alaska",
         "zip" => "0185128",
         "lead_created_at" => "2015-10-14T00:00:00.000Z",
         "free_trial_started_at" => "2015-11-01T00:00:00.000Z",
         "company" => "",
    )),
    "many more" => "..."
  )))
));
?>
(*chartmogul.Customers)(0xc042088b40)({
 Entries: ([]*chartmogul.Customer) (len=2) {
  (*chartmogul.Customer)(0xc0421e6160)({
   ID: (uint32) 4861688,
   DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
   UUID: (string) (len=40) "cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
   ExternalID: (string) (len=8) "cus_0001",
   Name: (string) (len=10) "Adam Smith",
   Email: (string) (len=14) "[email protected]",
   Status: (string) (len=4) "Lead",
   CustomerSince: (string) "",
   Attributes: (*chartmogul.Attributes)(0xc042006600)({
    Tags: ([]string) {
    },
    Stripe: (*chartmogul.Stripe)(0xc04200c4c0)({
     UID: (uint64) 0,
     Coupon: (bool) false
    }),
    Clearbit: (*chartmogul.Clearbit)(0xc042110060)({
     ID: (string) "",
     Name: (string) "",
     LegalName: (string) "",
     Domain: (string) "",
     URL: (string) "",
     Metrics: (map[string]interface {}) <nil>,
     Category: (*chartmogul.Category)(<nil>)
    }),
    Custom: (map[string]interface {}) {
    }
   }),
   Address: (*chartmogul.Address)(0xc042008440)({
    AddressZIP: (string) "",
    City: (string) (len=8) "New York",
    State: (string) "",
    Country: (string) (len=13) "United States"
   }),
   Mrr: (float64) 0,
   Arr: (float64) 0,
   BillingSystemURL: (string) "",
   ChartmogulURL: (string) (len=56) "https://app.chartmogul.com/#customers/4861688-Adam_Smith",
   BillingSystemType: (string) (len=10) "Custom",
   Currency: (string) (len=3) "USD",
   CurrencySign: (string) (len=1) "$",
   Company: (string) "",
   Country: (string) (len=2) "US",
   State: (string) "",
   City: (string) (len=8) "New York",
   LeadCreatedAt: (string) (len=24) "2015-10-14T00:00:00.000Z",
   FreeTrialStartedAt: (string) (len=24) "2015-11-01T00:00:00.000Z",
   Errors: (chartmogul.Errors) chartmogul: map[]
  }),
  (*chartmogul.Customer)(0xc0421e66e0)({
   ID: (uint32) 4863286,
   DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
   UUID: (string) (len=40) "cus_99529720-edfe-11e6-8773-13ec140c2da5",
   ExternalID: (string) (len=8) "cus_0002",
   Name: (string) (len=10) "Adam Smith",
   Email: (string) (len=14) "[email protected]",
   Status: (string) (len=4) "Lead",
   CustomerSince: (string) "",
   Attributes: (*chartmogul.Attributes)(0xc0420068d0)({
    Tags: ([]string) {
    },
    Stripe: (*chartmogul.Stripe)(0xc04200c5c0)({
     UID: (uint64) 0,
     Coupon: (bool) false
    }),
    Clearbit: (*chartmogul.Clearbit)(0xc0421100c0)({
     ID: (string) "",
     Name: (string) "",
     LegalName: (string) "",
     Domain: (string) "",
     URL: (string) "",
     Metrics: (map[string]interface {}) <nil>,
     Category: (*chartmogul.Category)(<nil>)
    }),
    Custom: (map[string]interface {}) {
    }
   }),
   Address: (*chartmogul.Address)(0xc0420084c0)({
    AddressZIP: (string) "",
    City: (string) (len=8) "New York",
    State: (string) "",
    Country: (string) (len=13) "United States"
   }),
   Mrr: (float64) 0,
   Arr: (float64) 0,
   BillingSystemURL: (string) "",
   ChartmogulURL: (string) (len=56) "https://app.chartmogul.com/#customers/4863286-Adam_Smith",
   BillingSystemType: (string) (len=10) "Custom",
   Currency: (string) (len=3) "USD",
   CurrencySign: (string) (len=1) "$",
   Company: (string) "",
   Country: (string) (len=2) "US",
   State: (string) "",
   City: (string) (len=8) "New York",
   LeadCreatedAt: (string) (len=24) "2015-10-14T00:00:00.000Z",
   FreeTrialStartedAt: (string) (len=24) "2015-11-01T00:00:00.000Z",
   Errors: (chartmogul.Errors) chartmogul: map[]
  })
 },
 Page: (uint32) 1,
 PerPage: (uint32) 2,
 HasMore: (bool) true,
 CurrentPage: (int32) 1,
 TotalPages: (int32) 7
})
Customers(entries=[<Customer{
    address=<Address{
        address_zip=None,
        city='New York',
        country='United States',
        state=None}>,
    arr=0.0,
    attributes=<Attributes{
        clearbit=<Clearbit{
        }>,
        custom={
        },
        stripe=<Stripe{
        }>,
        tags=[]}>,
    billing_system_type='Custom',
    billing_system_url=None,
    chartmogul_url='https://app.chartmogul.com/#customers/4861688-Adam_Smith',
    city='New York',
    company='',
    country='US',
    currency='USD',
    currency_sign='$',
    customer_since=None,
    data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11',
    data_source_uuids=['ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11'],
    email='[email protected]',
    external_id='cus_0001',
    external_ids=['cus_0001'],
    free_trial_started_at=datetime.datetime(2015, 11, 1, 0, 0),
    id=4861688,
    lead_created_at=datetime.datetime(2015, 10, 14, 0, 0),
    mrr=0.0,
    name='Adam Smith',
    state=None,
    status='Lead',
    uuid='cus_c0dc8d74-edfd-11e6-a357-832dddba822f',
    zip=None}>,
<Customer{
    address=<Address{
    address_zip=None,
    city='New York',
    country='United States',
    state=None}>,
    arr=0.0,
    attributes=<Attributes{
        clearbit=<Clearbit{
        }>,
        custom={
        },
        stripe=<Stripe{
        }>,
        tags=[]}>,
    billing_system_type='Custom',
    billing_system_url=None,
    chartmogul_url='https://app.chartmogul.com/#customers/4863286-Adam_Smith',
    city='New York',
    company='',
    country='US',
    currency='USD',
    currency_sign='$',
    customer_since=None,
    data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11',
    data_source_uuids=['ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11'],
    email='[email protected]',
    external_id='cus_0002',
    external_ids=['cus_0002'],
    free_trial_started_at=datetime.datetime(2015, 11, 1, 0, 0),
    id=4863286,
    lead_created_at=datetime.datetime(2015, 10, 14, 0, 0),
    mrr=0.0,
    name='Adam Smith',
    state=None,
    status='Lead',
    uuid='cus_99529720-edfe-11e6-8773-13ec140c2da5',
    zip=None}>],
has_more=True,
per_page=2,
page=1,
current_page=1,
total_pages=7)

In the response, entries contains an array of customer objects with the following data:

  • id - The internal ChartMogul ID of the customer object.
  • uuid - The UUID of the customer object generated by ChartMogul.
  • external_id - The unique external identifier for this customer, if any.
  • external_ids - An array containing the unique external identifiers of all customer records that have been merged into this customer.
  • data_source_uuid - The ChartMogul UUID of the data source of this customer.
  • data_source_uuids - An array containing the ChartMogul UUIDs of all data sources that contribute data to this customer. This is most relevant for merged customers.
  • name - The name of this customer.
  • email - This customer's email address.
  • company - This customer's company name.
  • status - The status of this customer. One of Lead, Active, Past due or Cancelled.
  • lead_created_at - The time at which this customer was established as a lead, as specified by you.
  • free_trial_started_at - The time at which this customer started a free trial of your product or service, as specified by you.
  • customer-since - An RFC3339 formatted datetime attribute indicating when the customer first started paying for a subscription.
  • country - The country from the customer's address.
  • state - The state from the customer's address.
  • city - The city from the customer's address.
  • zip - The zip code from the customer's address.
  • attributes - A JSON object representing this customer's attributes containing the following data:
    • tags - An Array of tags that you have added to this customer.
    • stripe - A JSON object representing any metadata on this customer object in your Stripe account.
    • clearbit - A JSON object representing publicly available information about this customer retrieved from Clearbit.
    • custom - A JSON object representing custom attributes that you have added to this customer.
  • address - A JSON object representing this customer's address containing the following data:
    • address_zip - The zip code from this customer's address.
    • city - The city from this customer's address.
    • state - The state from this customer's address.
    • country - The country code from this customer's address as per the ISO-3166 alpha-2 standard.
  • mrr - The current monthly recurring revenue for this customer, expressed in the currency selected for your account, as an integer number of cents. Divide by 100 to obtain the actual amount.
  • arr - The current annual run rate for this customer, also expressed as an integer number of cents in your account's selected currency.
  • billing-system-url - A URL for this customer's data in your billing system, if available.
  • chartmogul-url - The URL for this customer's ChartMogul page. This is only accessible to a user logged in to your ChartMogul account.
  • billing-system-type - The type of the billing system from where the customer was imported to ChartMogul. For example, Stripe, Recurly, Chargify, or Custom.
  • currency - The currency of the MRR readings for this customer.
  • currency-sign - Text representation to display the currency. E.g. $, or €.

The other keys represent pagination attributes:

  • has_more - One of true or false depending on whether there are more pages with results for this request.
  • per_page - The number of results in this response.
  • page - The page number of this response.
  • total_pages - The total number of pages with results for this request.
  • current_page - The page number of this response.

📘

Retrieving customers created using the API

You can use one of two filters to retrieve a list of customers created using the API.

  • use the data_source_uuid filter to retrieve customers belonging to a specific Custom data source, or
  • use the system filter and specify the value as Custom to retrieve customers belonging to all Custom data sources.
Language
Authentication
Basic
base64
: