Reference
Help Center

List Customers

get https://api.chartmogul.com/v1/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(per_page: 50)

ChartMogul.Customer.all(config, { per_page: 50 });

ChartMogul\Customer::all(["per_page" => 50]);

api.ListCustomers(&cm.ListCustomersParams{Cursor: cm.Cursor{PerPage: 50}})

chartmogul.Customer.all(config, per_page=50)
Result Format
{
  "entries": [
    {
      "id": 25647,
      "uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
      "external_id": "34916129",
      "name": "Example Company",
      "email": "[email protected]",
      "status": "Active",
      "customer-since": "2023-06-09T13:16:00-04:00",
      "attributes": {
        "tags": ["engage", "unit loss", "discountable"],
        "stripe": {
          "uid": 7,
          "coupon": true
        },
        "clearbit": {},
        "custom": {
          "CAC": 213,
          "utmCampaign": "social media 1",
          "convertedAt": "2023-09-08 00:00:00",
          "pro": false,
          "salesRep": "Gabi"
        }
      },
      "address": {
        "address_zip": "0185128",
        "city": "Nowhereville",
        "state": "Alaska",
        "country": "US"
      },
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "data_source_uuids": ["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
      "external_ids": ["34916129"],
      "company": "",
      "country": "US",
      "state": "AK",
      "city": "Nowhereville",
      "zip": "0185128",
      "lead_created_at": null,
      "free_trial_started_at": null,
      "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": "$"
    }
    // ...and more
  ],
  "per_page": 50, // deprecated in response, but can be used as a query parameter
  "page": 1, // deprecated
  "current_page": 1, // deprecated
  "total_pages": 4, // deprecated
  "cursor": "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  "has_more": true
}

#<ChartMogul::Customers:0x007fe7e09ca7c8 
  @entries=[
    #<ChartMogul::Customer:0x007fe7e09ca408 
      @id=25647, 
      @uuid="cus_de305d54-75b4-431b-adb2-eb6b9e546012",
      @data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      @data_source_uuids=["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
      @external_id="34916129",
      @external_ids=["34916129"],
      @name="Example Company", 
      @email="[email protected]", 
      @status="Active",
      @lead_created_at=null,
      @free_trial_started_at=null,
      @customer_since=2023-06-09 13:16:00 -04:00:00,
      @country="US",
      @state="AK",
      @city="Nowhereville",
      @zip="0185128",
      @attributes={
        :tags=>["engage", "unit loss", "discountable"], 
        :stripe=>{
          :uid=>7,
          :coupon=>true
        },
        :clearbit=>{},
        :custom=>{
          :CAC=> 213,
          :utmCampaign=> "social media 1",
          :convertedAt=> "2023-09-08 00:00:00",
          :pro=> false,
          :salesRep=> "Gabi"
        }
      }, 
      @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="$"
    >,
    # // ...and more
  ], 
  @per_page=50, # deprecated with version 4.0.0, but can be used as query parameter
  @page=1, # deprecated with version 4.0.0
  @current_page=1, # deprecated with version 4.0.0
  @total_pages=3, # deprecated with version 4.0.0
  @cursor="AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  @has_more=true
>

{
  entries: [
    {
      id: 25647,
      uuid: "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
      external_id: "34916129",
      name: "Example Company",
      email: "[email protected]",
      status: "Active",
      "customer-since": "2023-06-09T13:16:00-04:00",
      attributes: {
        tags: ["engage", "unit loss", "discountable"],
        stripe: {
          uid: 7,
          coupon: true
        },
        clearbit: {},
        custom: {
          CAC: 213,
          utmCampaign: "social media 1",
          convertedAt: "2023-09-08 00:00:00",
          pro: false,
          salesRep: "Gabi"
        }
      },
      address: {
        address_zip: "0185128",
        city: "Nowhereville",
        state: "Alaska",
        country: "US"
      },
      data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      data_source_uuids: ["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
      external_ids: ["34916129"],
      company: "",
      country: "US",
      state: "AK",
      city: "Nowhereville",
      zip: "0185128",
      lead_created_at: null,
      free_trial_started_at: null,
      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": "$"
    }
    // ...and more
  ],
  per_page: 50, // deprecated with version 3.0.0, but can be used as a query parameter
  page: 1, // deprecated with version 3.0.0
  current_page: 1, // deprecated with version 3.0.0
  total_pages: 4, // deprecated with version 3.0.0
  cursor: "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  has_more: true
}

ChartMogul\Customers::__set_state(array(
  "current_page" => 1, # deprecated with version 6.0.0
  "total_pages" => 3, # deprecated with version 6.0.0
  "per_page" => 50, # deprecated with version 6.0.0, but can be used as query parameter
  "page" => 1, # deprecated with version 6.0.0
  "cursor" => "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  "has_more" => true,
  "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" => "2023-06-09T13:16:00-04:00",
        "attributes" => array(
          "custom" => array(
            "CAC" => 213,
            "utmCampaign" => "social media 1",
            "convertedAt" => "2023-09-08 00 =>00 =>00",
            "pro" => false,
            "salesRep" => "Gabi"
          ),
          "clearbit" => array(),
          "stripe" => array(
            "uid" => 7,
            "coupon" => true
          ),
          "tags" => array(
            0 => "engage",
            1 => "unit loss",
            2 => "discountable"
          ),
        ),
        "address" => array(
          "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_fef05d54-47b4-431b-aed2-eb6b9e545430",
        "data_source_uuids" => array(
          0 => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
        ),
        "external_ids" => array(
          0 => "cus_0001",
        ),
        "city" => "Nowhereville",
        "country" => "US",
        "state" => "AK",
        "zip" => "0185128",
        "lead_created_at" => null,
        "free_trial_started_at" => null,
        "company" => ""
      )),
      // ...and more
    )
  ))
));

(*chartmogul.Customers)(0xc042088b40)({
  Entries: ([]*chartmogul.Customer) (len=2) {
   (*chartmogul.Customer)(0xc0421e6160)({
     ID: (uint32) 25647,
     DataSourceUUID: (string) (len=39) "ds_80686670-cc45-11e6-b9da-ff67b9895fe3",
     DataSourceUUIDs: ([]string) {
       (len=39) "ds_fef05d54-47b4-431b-aed2-eb6b9e545430"
     },
     UUID: (string) (len=40) "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
     ExternalID: (string) (len=8) "cus_0001",
     ExternalIDs: ([]string) {
       (len=8) "cus_0001"
     },
     Name: (string) (len=10) "Adam Smith",
     Email: (string) (len=14) "[email protected]",
     Status: (string) (len=6) "Active",
     CustomerSince: (string) (len=25) "2023-06-09T13:16:00-04:00",
     Attributes: (*chartmogul.Attributes)(0xc042132b10)({
       Tags: ([]string) {
       },
       Stripe: (*chartmogul.Stripe)(0xc04212f5d0)({
       UID: (uint64) 0,
       Coupon: (bool) false
       }),
       Clearbit: (*chartmogul.Clearbit)(0xc0420f8cc0)({
       }),
       Custom: (map[string]interface {}) {
       }
     }),
     Address: (*chartmogul.Address)(0xc042009800)({
       AddressZIP: (string) "",
       City: (string) (len=8) "New York",
       State: (string) "",
       Country: (string) (len=13) "United States"
     }),
     Mrr: (float64) 4100,
     Arr: (float64) 49200,
     BillingSystemURL: (string) "",
     ChartmogulURL: (string) (len=54) "https://app.chartmogul.com/#customers/25647-Example_Company",
     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",
     Zip: (string) "",
     LeadCreatedAt: (string) "",
     FreeTrialStartedAt: (string) "",
     Errors: (chartmogul.Errors) chartmogul: map[]
   }),
   // ...and more
  },
  Page: (uint32) 1, // deprecated with version v4
  PerPage: (uint32) 50, // deprecated with version v4, but can be used as query parameter
  CurrentPage: (int32) 1, // deprecated with version v4
  TotalPages: (int32) 7, // deprecated with version v4
  Cursor: (string) (len=44) "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  HasMore: (bool) true,
 })

Customers(
  entries=[
    <Customer{
      address=<Address{
        address_zip=None, 
        city="New York", 
        country="United States", 
        state=None}>, 
      arr=49200.0, 
      attributes=<Attributes{
        clearbit=<Clearbit{
        }>, 
        custom={
        }, 
        stripe=<Stripe{
        }>, 
        tags=[]}>, 
      billing_system_type="Custom", 
      billing_system_url=None, 
      chartmogul_url="https://app.chartmogul.com/#customers/25647-Example_Company", 
      city="New York", 
      company="", 
      country="US", 
      currency="USD", 
      currency_sign="$", 
      customer_since=datetime.datetime(2023, 6, 9, 13, 16), 
      data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430", 
      data_source_uuids=["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"], 
      email="[email protected]", 
      external_id="cus_0001", 
      external_ids=["cus_0001"], 
      free_trial_started_at=None, 
      id=25647, 
      lead_created_at=None, 
      mrr=4100.0, 
      name="Adam Smith", 
      state=None, 
      status="Active", 
      uuid="cus_de305d54-75b4-431b-adb2-eb6b9e546012", 
      zip=None},
    # ...and more
  ],
  per_page=50, # deprecated with version 4.0.0, but can be used as query parameter
  page=1, # deprecated with version 4.0.0
  current_page=1, # deprecated with version 4.0.0
  total_pages=7, # deprecated with version 4.0.0
  cursor="AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
  has_more=True
)

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.
  • 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 - DEPRECATED The customer's name. This parameter is getting deprecated. Instead, use the first_name and last_name of the contact object when importing data into ChartMogul.
  • email - DEPRECATED The customer's email address. This parameter is getting deprecated. Instead, use the email of the contact object when importing data into ChartMogul.
  • company - This customer's company name.
  • status - The status of this customer. One of New Lead, Working Lead, Qualified Lead, Unqualified 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 US state where the customer is located — the last two letters of the US state code as per the ISO-3166-2 standard. For example, CA or NY.
  • 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. This is a legacy field. ChartMogul no longer utilizes 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, 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:

  • cursor - A value that should be used in the next API request to fetch next page of customers. Request for the next page should be initiated only if has_more is set to true indicating that there are more customers to list.
  • has_more - One of true or false depending on whether there are more pages with results for this request.
  • per_page - DEPRECATED The number of results in this response.
  • page - DEPRECATED The page number of this response.
  • total_pages - DEPRECATEDThe total number of pages with results for this request.
  • current_page - DEPRECATEDThe 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
Credentials
Basic
base64
: