> ## Documentation Index
> Fetch the complete documentation index at: https://docs.explo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Get or Create Customer

This endpoint gets or creates a new customer. If a customer with the given provided\_id does not exist, a new customer will be created. The response contains the created or already-existing customer and a flag denoting whether a new customer was created.

### Body

<ParamField body="name" type="string">
  The display name of your customer in Explo.
</ParamField>

<ParamField body="provided_id" type="string">
  The ID you use to identify this customer in your database. This is also the ID you will use to
  reference your customer in Explo queries or access your customer via the API. For more information
  on example usage, check out [this section](/creating-dashboards/variables/tips).
</ParamField>

<ParamField body="mapping" type="object">
  A set of key-values pairs that map a schema id to the data source that this customer loads data
  from. For more information on schemas and data sources, check out [this
  section](/data-sources/data-sources-and-schema/).
</ParamField>

<ParamField body="is_demo_group" type="boolean">
  A boolean representing whether this customer is a "demo customer." Setting this to true will make
  data panels include a demo watermark for the customer. Demo customers do not count towards paid
  customers. Default value is false.
</ParamField>

<ParamField body="emails" type="string[]">
  An array of email addresses to add to the customer.
</ParamField>

<ParamField body="group_tags" type="string[]">
  An array of group tag names to assign to the customer. Group tag names must be of existing group
  tags, and these can be created with the create\_group\_tag endpoint.
</ParamField>

<ParamField body="hierarchy_level_name" type="string">
  The name of the hierarchy level to assign to the customer. Must be an existing hierarchy level. If
  no level is specified, the created customer will be assigned to the root (highest) level of the
  hierarchy. If you do not have a hierarchy set up and would like one, reach out to customer
  support.
</ParamField>

<ParamField body="parent_provided_id" type="string">
  An identifier for a parent customer matching the parent's `provided_id`. If provided, the customer
  will be set as a child of the parent customer, and will have its `computed_properties` and
  `computed_parent_schema_datasource_mapping` fields inherit values from the parent customer.
  Parents must belong to the same data visibility group as their children. Parents must also be at a
  strictly higher hierarchy level than their children, so you'll need to explicitly set the
  `hierarchy_level_name` to be at a level below the parent's level. You can contact customer support
  to set up a hierarchy for your customers.
</ParamField>

<ParamField body="properties" type="object">
  A set of key-value pairs assigned to this customer. These will be accessible through variables in
  the dashboards and SQL editor. More information on properties can be found in [this
  section](/creating-dashboards/variables/passing-in-variables).
</ParamField>

### Response

<ResponseField name="success" type="number">
  Indicates whether the call was successful. 1 if successful, 0 if not.
</ResponseField>

<ResponseField name="new_customer" type="boolean">
  Indicates whether a new customer was created.
</ResponseField>

<ResponseField name="customer" type="object">
  The contents of the customer

  <Expandable title="Toggle object">
    <ResponseField name="token" type="string">
      The customer token (customerToken or CUSTOMER\_TOKEN) that will be used to identify which customer
      is viewing the dashboard. You should save this on your end to use when rendering an embedded
      dashboard by passing this token into the web component or iframe. Example usage
      [here](/embedding-documentation/dashboard/option-1-web-component/).
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name you provided for your customer in Explo.
    </ResponseField>

    <ResponseField name="provided_id" type="string">
      The ID you use to identify this customer in your database that you provided. This is also the ID
      you will use to reference your customer in Explo queries or access your customer via the API. For
      more information on example usage, check out [this section](/creating-dashboards/variables/tips).
    </ResponseField>

    <ResponseField name="emails" type="object">
      An array of email addresses you provided for your customer.
    </ResponseField>

    <ResponseField name="group_tags" type="object">
      An array of group tag names that have been assigned to this customer.
    </ResponseField>

    <ResponseField name="hierarchy_level" type="string">
      The name of the assigned hierarchy level.
    </ResponseField>

    <ResponseField name="access_group" type="string or null">
      If present, the name of the assigned data visibility group.
    </ResponseField>

    <ResponseField name="is_demo_group" type="boolean">
      True if this customer is a demo customer, which means that data panels will include a demo
      watermark for the customer. Demo customers do not count towards paid customers.
    </ResponseField>

    <ResponseField name="properties" type="JSON or null">
      A set of key-value pairs assigned to this customer. These will be accessible through variables in
      the dashboards and SQL editor. More information on properties can be found in [this
      section](/creating-dashboards/variables/passing-in-variables).
    </ResponseField>

    <ResponseField name="computed_properties" type="JSON">
      A properties object based on the provided properties of this customer and any inherited properties
      from parent customers.
    </ResponseField>

    <ResponseField name="parent_schema_datasource_mapping" type="JSON | Null">
      A set of key-values pairs that map a schema id to the data source that this customer loads data
      from. For more information on schemas and data sources, check out [this
      section](/data-sources/data-sources-and-schema/).
    </ResponseField>

    <ResponseField name="computed_parent_schema_datasource_mapping" type="JSON">
      A schema datasource mapping object based on the parent\_schema\_datasource\_mapping of the customer
      and any inherited parent\_schema\_datasource\_mapping from parent customers.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Example Request theme={null}
  curl --location --request POST 'https://api.explo.co/api/create_customer/' \
  --header 'Content-Type: application/json' \
  --header 'Explo-Authorization: Token <token>' \
  --data-raw '{
      "provided_id": "example_1",
      "name": "Example 1",
      "mapping": {"40": "213", "134": "386"},
      "properties": {"filterValue": "value"},
      "emails": ["example@example.com"],
      "group_tags" : ["sales"],
      "hierarchy_level_name": "Customer"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": 1,
    "new_customer": true,
    "customer": {
      "token": "<customer_token_to_auth_dashboard>",
      "name": "Example 1",
      "provided_id": "example_1",
      "is_demo_group": false,
      "emails": ["example@example.com"],
      "group_tags": ["sales"],
      "properties": { "filterValue": "value" },
      "computed_properties": { "filterValue": "value" },
      "access_group": "Production",
      "parent_schema_datasource_mapping": {"40": "213": "134": 386"},
      "computed_parent_schema_datasource_mapping": {"40": "213": "134": 386"},
      "hierarchy_level": "Customer"
    }
  }
  ```
</ResponseExample>