Create a Customer

POST https://api.chartmogul.com/v1/customers

Creates a customer object in ChartMogul under the specified data_source.

curl -X POST "https://api.chartmogul.com/v1/customers" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
            "external_id": "cus_0001",
            "name": "Adam Smith",
            "email": "[email protected]",
            "country": "US",
            "state": "US-NY",
            "city": "New York",
            "company": "Pinata Technologies",
            "lead_created_at": "2022-10-14 00:00:00",
            "free_trial_started_at": "2022-11-01 00:00:00",
            "owner": "[email protected]",
            "attributes": {
              "tags": ["important", "Prio1"],
              "custom": [
                { "type": "String", "key": "channel", "value": "Facebook", "source": "integration" },
                { "type": "Integer", "key": "age", "value": 18 }
              ]
            },
            "primary_contact": {
              "first_name": "Anna",
              "last_name": "Gardner",
              "email": "[email protected]",
              "title": "CFO",
              "phone": "+123456789",
              "linked_in": "https://linkedin.com/example",
              "twitter": "https://twitter.com/example",
              "notes": "Heading\nBody\nFooter"
            },
            "website_url": "https://example.com"
        }'

ChartMogul::Customer.create!(
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  external_id: "cus_0001",
  name: "Adam Smith",
  email: "[email protected]",
  country: "US",
  state: "US-NY",
  city: "New York",
  company: "Pinata Technologies",
  lead_created_at: Time.utc(2022, 10, 14),
  free_trial_started_at: Time.utc(2022, 11, 1),
  attributes: {
    tags: ["important", "Prio1"],
    custom: [
      { type: "String", key: "channel", value: "Facebook", source: "integration" },
      { type: "Integer", key: "age", value: 18 },
    ],
  },
  website_url: "https://example.com",
)

ChartMogul.Customer.create(config, {
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  external_id: "cus_0001",
  name: "Adam Smith",
  email: "[email protected]",
  country: "US",
  state: "US-NY",
  city: "New York",
  company: "Pinata Technologies",
  lead_created_at: "2022-10-14",
  free_trial_started_at: "2022-11-01",
  attributes: {
    tags: ["important", "Prio1"],
    custom: [
      {
        type: "String",
        key: "channel",
        value: "Facebook",
        source: "integration",
      },
      { type: "Integer", key: "age", value: 18 },
    ],
  },
  website_url: "https://example.com",
});

ChartMogul\Customer::create([
  "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "external_id" => "cus_0001",
  "name" => "Adam Smith",
  "email" => "[email protected]",
  "country" => "US",
  "state" => "US-NY",
  "city" => "New York",
  "company" => "Pinata Technologies",
  "lead_created_at" => "2022-10-14",
  "free_trial_started_at" => "2022-11-01",
  "attributes" => [
    "tags" => ["important", "Prio1"],
    "custom" => [
      ["type" => "String", "key" => "channel", "value" => "Facebook", "source" => "integration"],
      ["type" => "Integer", "key" => "age", "value" => 18],
    ],
  ],
  "website_url" => "https://example.com",
]);

api.CreateCustomer(&cm.NewCustomer{
  DataSourceUUID:     "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  ExternalID:         "cus_0001",
  Name:               "Adam Smith",
  Email:              "[email protected]",
  Country:            "US",
  State:              "US-NY",
  City:               "New York",
  Company:            "Pinata Technologies",
  LeadCreatedAt:      "2022-10-14",
  FreeTrialStartedAt: "2022-11-01",
  Attributes: &cm.NewAttributes{
    Tags: []string{"important", "Prio1"},
    Custom: []*cm.CustomAttribute{
      {Type: "String", Key: "channel", Value: "Facebook", Source: "integration"},
      {Type: "Integer", Key: "age", Value: 18},
    },
  },
  WebsiteUrl: "https://example.com",
});

chartmogul.Customer.create(
  config,
  data={
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "external_id": "cus_0001",
    "name": "Adam Smith",
    "email": "[email protected]",
    "country": "US",
    "state": "US-NY",
    "city": "New York",
    "company": "Pinata Technologies",
    "lead_created_at": "2022-10-14",
    "free_trial_started_at": "2022-11-01",
    "attributes": {
      "tags": ["important", "Prio1"],
      "custom": [
        {
          "type": "String",
          "key": "channel",
          "value": "Facebook",
          "source": "integration",
        },
        {
          "type": "Integer",
          "key": "age",
          "value": 18
        },
      ],
    },
    "website_url": "https://example.com",
  },
)

{
  "id": 74596,
  "uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "external_id": "cus_0001",
  "external_ids": ["cus_0001"],
  "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "data_source_uuids": ["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
  "name": "Adam Smith",
  "email": "[email protected]",
  "company": "Pinata Technologies",
  "status": "Active",
  "lead_created_at": "2022-10-14T00:00:00.000Z",
  "free_trial_started_at": "2022-11-01T00:00:00.000Z",
  "customer-since": null,
  "zip": null,
  "city": "New York",
  "state": "NY",
  "country": "US",
  "address": {
    "address_zip": null,
    "city": "New York",
    "state": "New York",
    "country": "United States"
  },
  "attributes": {
    "tags": ["important", "Prio1"],
    "custom": { "channel": "Facebook", "age": 18 },
    "stripe": {}
  },
  "mrr": 0,
  "arr": 0,
  "billing-system-type": "Custom",
  "billing-system-url": null,
  "chartmogul-url": "https://app.chartmogul.com/#/customers/74596-Pinata_Technologies",
  "currency": "USD",
  "currency-sign": "$",
  "owner": "[email protected]",
  "website_url": "https://example.com"
}

<ChartMogul::Customer:0x000000006615e8
  @id=74596,
  @uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  @external_id="cus_0001",
  @external_ids=["cus_0001"],
  @data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  @data_source_uuids=["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"]
  @name="Adam Smith",
  @email="[email protected]",
  @company="Pinata Technologies",
  @status="Active",
  @lead_created_at=2022-10-24 00:00:00 UTC,
  @free_trial_started_at=2022-11-01 00:00:00 UTC,
  @customer_since=nil,
  @zip=nil,
  @city="New York",
  @state="NY",
  @country="US",
  @address={
    :address_zip=>nil,
    :city=>"New York",
    :state=>"New York",
    :country=>"United States",
  },
  @attributes={
    :tags=>["important", "Prio1"],
    :custom=>{:channel=>"Facebook", :age=>18},
    :stripe=>{},
  },
  @mrr=0,
  @arr=0,
  @billing_system_type="Custom",
  @billing_system_url=nil,
  @chartmogul_url="https://app.chartmogul.com/#/customers/74596-Pinata_Technologies",
  @currency="USD",
  @currency_sign="$",
  @owner="[email protected]",
  @website_url="https://example.com",
>

{
  id: 74596,
  uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  external_id: "cus_0001",
  external_ids: ["cus_0001"],
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  data_source_uuids: ["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
  name: "Adam Smith",
  email: "[email protected]",
  company: "Pinata Technologies",
  status: "Active",
  lead_created_at: "2022-10-14T00:00:00.000Z",
  free_trial_started_at: "2022-11-01T00:00:00.000Z",
  "customer-since": null,
  zip: null,
  city: "New York",
  state: "NY",
  country: "US",
  address: {
    address_zip: null,
    city: "New York",
    state: "New York",
    country: "United States"
  },
  attributes: {
    tags: ["important", "Prio1"],
    custom: { channel: "Facebook", age: 18 },
    stripe: {}
  },
  mrr: 0,
  arr: 0,
  "billing-system-type": "Custom",
  "billing-system-url": null,
  "chartmogul-url": "https://app.chartmogul.com/#/customers/74596-Pinata_Technologies",
  currency: "USD",
  "currency-sign": "$",
  owner: "[email protected]",
  website_url: "https://example.com"
}

ChartMogul\Customer::__set_state(array(
  "id" => 74596,
  "uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "external_id" => "cus_0001",
  "external_ids" => array(
    0 => "cus_0001",
  ),
  "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "data_source_uuids" => array(
    0 => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  ),
  "name" => "Adam Smith",
  "email" => "[email protected]",
  "company" => "Pinata Technologies",
  "status" => "Active",
  "lead_created_at" => "2022-10-14T00:00:00.000Z",
  "free_trial_started_at" => "2022-11-01T00:00:00.000Z",
  "customer_since" => NULL,
  "zip" => NULL,
  "city" => "New York",
  "state" => "NY",
  "country" => "US",
  "address" => array(
    "address_zip" => NULL,
    "city" => "New York",
    "state" => "New York",
    "country" => "United States",
  ),
  "attributes" => array(
    "tags" => array(
      0 => "important",
      1 => "Prio1",
    ),
    "custom" => array(
      "channel" => "Facebook",
      "age" => 18,
    ),
    "stripe" => array(),
  ),
  "mrr" => 0,
  "arr" => 0,
  "billing_system_type" => "Custom",
  "billing_system_url" => NULL,
  "chartmogul_url" => "https://app.chartmogul.com/#/customers/74596-Pinata_Technologies",
  "currency" => "USD",
  "currency_sign" => "$",
  "owner" => "[email protected]",
  "website_url" => "https://example.com",
))

(*chartmogul.Customer)(0xc0420706e0)({
  ID: (uint32) 74596,
  UUID: (string) (len=40) "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  ExternalID: (string) (len=8) "cus_0001",
  ExternalIDs: ([]string) (len=1 cap=1) {
    (string) (len=8) "cus_0001",
  },
  DataSourceUUID: (string) (len=39) "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  DataSourceUUIDs: ([]string) (len=1 cap=1) {
    (string) (len=39) "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  },
  Name: (string) (len=10) "Adam Smith",
  Email: (string) (len=16) "[email protected]",
  Company: (string) (len=19) "Pinata Technologies",
  Status: (string) (len=6) "Active",
  LeadCreatedAt: (string) (len=24) "2022-10-14T00:00:00.000Z",
  FreeTrialStartedAt: (string) (len=24) "2022-11-01T00:00:00.000Z",
  CustomerSince: (string) "",

  City: (string) (len=8) "New York",
  State: (string) (len=2) "NY",
  Country: (string) (len=2) "US",
  Address: (*chartmogul.Address)(0xc0421e4000)({
    AddressZIP: (string) "",
    City: (string) (len=8) "New York",
    State: (string) (len=8) "New York",
    Country: (string) (len=13) "United States",
  }),
  Attributes: (*chartmogul.Attributes)(0xc04221a3c0)({
    Tags: ([]string) (len=2 cap=4) {
      (string) (len=9) "important",
      (string) (len=5) "Prio1"
    },
    Custom: (map[string]interface {}) (len=2) {
      (string) (len=7) "channel": (string) (len=8) "Facebook",
      (string) (len=3) "age": (float64) 18
    },
    Stripe: (map[string]interface {}) {},
    Clearbit: (map[string]interface {}) {}, // deprecated
  }),
  Mrr: (float64) 0,
  Arr: (float64) 0,
  BillingSystemType: (string) (len=10) "Custom",
  BillingSystemURL: (string) "",
  ChartmogulURL: (string) (len=56) "https://app.chartmogul.com/#/customers/74596-Pinata_Technologies",
  Currency: (string) (len=3) "USD",
  CurrencySign: (string) (len=1) "$",
  Owner: (string) (len=18) "[email protected]",
  WebsiteUrl: (string) (len=19) "https://example.com",
  Errors: (chartmogul.Errors) chartmogul: map[],
})

<Customer{
  id=74596,
  uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  external_id="cus_0001",
  external_ids=["cus_0001"],
  data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  data_source_uuids=["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
  name="Adam Smith",
  email="[email protected]",
  company="Pinata Technologies",
  status="Active",
  free_trial_started_at=datetime.datetime(2022, 11, 1, 0, 0),
  lead_created_at=datetime.datetime(2022, 10, 14, 0, 0),
  customer_since=None,
  zip=None,
  city="New York",
  state="NY",
  country="US",
  address=<Address{
    address_zip=None,
    city="New York",
    state="New York",
    country="United States",
  }>,
  attributes=<Attributes{
    tags=["important", "Prio1"],
    custom={channel: "Facebook", age: 18},
    stripe={},
  }>,
  mrr=0.0,
  arr=0.0,
  billing_system_type="Custom",
  billing_system_url=None,
  chartmogul_url="https://app.chartmogul.com/#/customers/74596-Pinata_Technologies",
  currency="USD",
  currency_sign="$",
  owner: "[email protected]",
  website_url="https://example.com",
}>

Body parameters

data_source_uuid string required

The ChartMogul UUID of the source that this customer is from.

external_id string required

A unique identifier specified by you, typically one from your internal system. Accepts alphanumeric characters only.

name string deprecated

The customer's name for display purposes. Instead of the customer name, use the contact object to import the first and last name of a contact person.

email string deprecated

The customer's email address. Instead of the customer email, use the contact object to import the email of a contact person.

company string

The customer's company or organisation.

country string

Country code of customer's location as per ISO-3166 alpha-2 standard, e.g. US or DE.

state string

The US state where the customer is located — the US state code as per the ISO-3166-2 standard. For example, US-CA or US-NY.

city string

City of the customer's location.

zip string

Zip code of the customer's location.

lead_created_at string

Time at which this customer was established as a lead. Must be an ISO 8601-formatted time, in the past. The timezone defaults to UTC unless otherwise specified.

free_trial_started_at string

Time at which this customer started a free trial of your product or service. Must be an ISO 8601-formatted time, in the past. The timezone defaults to UTC unless otherwise specified. This is expected to be the same as, or after the lead_created_at value.

attributes object

An object containing additional attributes of the customer in the form of tags and custom attributes as described below.

tags array(string)

An array of tags to be added to the customer.

custom array(object)

An array of custom attributes to be added to the customer. Each custom attribute must have a type, key, and value as described below.

type string required: The data type of the custom attribute. Must be one of String, Integer, Decimal, Timestamp or Boolean.
key string required: The name of the custom attribute. Only accepts alphanumeric characters and underscores.
value string required: The value of the custom attribute. Should be of the data type specified in type.
source string default: "API": Optional parameter to specify where the custom attribute was created, displayed in the ChartMogul UI. Defaults to API. Not included in the response.

owner string

The email address of the user that owns this customer. A user with this email must already exist.

primary_contact object

Primary contact specified for this customer. To add more than one contact, use the "Create a Contact" endpoint.

first_name string: The first name of the contact
last_name string: The last name of the contact
email string: The contact's email address
title string: The job title of the contact, e.g. "CEO"
phone string: The contact's phone number
linked_in string: The URL of the contact's LinkedIn profile
twitter string: The URL of the contact's Twitter profile
notes string: Additional notes or comments about the contact. Newline can be appended with \n in the string.

website_url string

The URL of the customer’s website. The protocol is optional and defaults to https://.

Response

The response object contains the following data:

id

The internal ChartMogul ID for the customer object.

uuid

The ChartMogul UUID for the customer.

external_id

The unique external identifier for the customer. It usually originates from a billing system outside of ChartMogul.

external_ids

An array containing the unique external identifiers of both the customer itself as well as all customer records that have been merged into it.

data_source_uuid

The ChartMogul UUID for the source the customer is from.

data_source_uuids

An array containing the ChartMogul UUIDs for the source the customer is from as well as the UUIDs for the sources of customers merged into it.

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

The customer's company name.

status

The customer status. One of New Lead, Working Lead, Qualified Lead, Unqualified Lead, Active, Past Due, or Cancelled.

lead_created_at

The time the customer was established as lead. This is given as ISO 8601-formatted string, except in the Ruby and Python libraries (where they are given as datetime objects).

free_trial_started_at

The time at which the customer started a free trial. This is given as ISO 8601-formatted string, except in the Ruby and Python libraries (where they are given as datetime objects).

customer-since

The time at which the customer started their first subscription. This is given as ISO 8601-formatted string, except in the Ruby and Python libraries (where they are given as datetime objects).

zip

The zip code from the customer's address, as a string.

city

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

country

The country from customer's address, as ISO 3166-1 alpha-2-formatted string.

address

An object containing the customer's address.

address_zip: The zip code from the customer's address.
city: The full name for the city from the customer's address.
state: The full name for the state from the customer's address.
country: The full name for the country from the customer's address.

attributes

An object containing tags, custom attributes, and Stripe metadata.

tags: An array of tags on the customer.
custom: An object containing the custom attributes on the custom, as key-value pairs.
stripe: An object with the customer's Stripe metadata. An empty object if the customer is not a Stripe customer.

mrr

The current monthly recurring revenue for this customer, expressed in your account currency, as an integer number of cents. For the actual amount, divide by 100.

arr

The current annual run rate for this customer, expressed in your account currency, as an integer number of cents. For the actual amount, divide by 100.

billing-system-type

The billing system the customer was imported from. For example Stripe, Recurly, Custom, etcetera.

billing-system-url

A URL for this customer linking to the customer record in your billing system, if available.

chartmogul-url

A URL for this customer linking to the customer record in ChartMogul.

currency

Your account currency. This is used to express MRR and ARR in.

currency-sign

The symbol(s) used to represent the currency, e.g. $, or €.

owner

The user responsible for the customer relationship.

website_url

The URL of the customer's website.