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

# Create Customer

> This endpoint creates a customer.

## Base URL `https://api.tolt.com`

<br />

### Body Parameters

<ParamField body="email*" type="string">
  Customer's email address
</ParamField>

<ParamField body="partner_id*" type="string">
  The partner ID who referred this customer
</ParamField>

<ParamField body="name" type="string - optional">
  Customer's name
</ParamField>

<ParamField body="subscription_id" type="string - optional">
  Associated subscription identifier
</ParamField>

<ParamField body="customer_id" type="string - optional">
  Your internal customer identifier
</ParamField>

<ParamField body="click_id" type="string - optional">
  Tracking click identifier
</ParamField>

<ParamField body="promotion_code" type="string - optional">
  Promotion code used to attribute this customer. The code must belong to the
  referring partner, their group, or their program. If it does not match, the
  customer is still created using click or API attribution, and the response
  includes a `warnings` array with a `promotion_code_not_applied` entry.
</ParamField>

<ParamField body="created_at" type="string - optional">
  ISO 8601 timestamp of when the customer was created
</ParamField>

<ParamField body="lead_at" type="string - optional">
  ISO 8601 timestamp of when the customer became a lead
</ParamField>

<ParamField body="active_at" type="string - optional">
  ISO 8601 timestamp of when the customer became active
</ParamField>

<ParamField body="status" type="string - optional">
  Customer's status. Valid values are: 'lead', 'trialing', 'active', 'canceled'
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the request was successful
</ResponseField>

<ResponseField name="data" type="array[object]">
  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="id" type="string">
      Unique identifier for the customer, `uuid` or prefixed with `cust_`
    </ResponseField>

    <ResponseField name="email" type="string">
      Your unique identifier for the customer
    </ResponseField>

    <ResponseField name="partner_id" type="string">
      ID of the referring partner
    </ResponseField>

    <ResponseField name="name" type="string">
      Customer's name
    </ResponseField>

    <ResponseField name="subscription_id" type="string">
      Associated subscription identifier
    </ResponseField>

    <ResponseField name="identifier" type="string">
      Customer identifier
    </ResponseField>

    <ResponseField name="customer_id" type="string">
      Your internal customer identifier
    </ResponseField>

    <ResponseField name="click_id" type="string">
      Tracking click identifier
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="lead_at" type="string">
      ISO 8601 timestamp of lead conversion
    </ResponseField>

    <ResponseField name="active_at" type="string">
      ISO 8601 timestamp of activation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of updated customer
    </ResponseField>

    <ResponseField name="status" type="string">
      Customer's current status
    </ResponseField>

    <ResponseField name="plan" type="string | null">
      Plan the customer subscribed to
    </ResponseField>

    <ResponseField name="promotion_code_id" type="string | null">
      Identifier for a promotoinal code used by the customer
    </ResponseField>

    <ResponseField name="program_id" type="string">
      Program ID the customer belongs to
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization ID
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST 'https://api.tolt.com/v1/customers' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
      "email": "cust_123",
      "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
      "name": "Jim Halpert",
      "subscription_id": "sub_456",
      "customer_id": "jim_halpert_789",
      "click_id": "click_abc",
      "promotion_code": "PARTNER20",
      "status": "active",
      "active_at": "2025-01-15T14:30:00.000Z"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "success": true,
    "data": [
      {
        "id": "cust_dK9bzRGn46BhVgNFHD6fDgXW",
        "customer_id": "jim_halpert_789",
        "identifier": "james@tolt.com",
        "email": "james@tolt.com",
        "name": "Jim Halpert",
        "status": "active",
        "plan": null,
        "subscription_id": "sub_456",
        "lead_at": "2025-04-25T11:00:00.797Z",
        "active_at": "2025-01-15T14:30:00.000Z",
        "click_id": "click_abc",
        "program_id": "prg_YRsbPDAKhWfdqJbFACheh",
        "partner_id": "part_s7mbzRGn46BhVgNFHD6fDgXW",
        "organization_id": "org_JE3mfYNL9ci7sFaJazAv2",
        "created_at": "2025-04-25T11:00:00.800Z",
        "updated_at": "2025-04-25T11:00:00.800Z",
        "promotion_code_id": "promo_abc"
      }
    ]
  }
  ```
</ResponseExample>