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

# Create or Update Customer

> Create or update customer records

## Overview

Creates or updates customer records in Telemetron.

**Behavior:**

* **Without `telemetronCustomerId`**: Creates new customer (409 error if email exists)
* **With `telemetronCustomerId`**: Updates existing customer

## Authentication

<ParamField header="x-api-key" type="string" required>
  Your organization's API key
</ParamField>

## Request Body

<ParamField body="email" type="string" required>
  Customer's email address (used as unique identifier)
</ParamField>

<ParamField body="name" type="string">
  Customer's full name (defaults to email prefix if not provided)
</ParamField>

<ParamField body="phone" type="string">
  Customer's phone number
</ParamField>

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

<ParamField body="telemetronCustomerId" type="string">
  Existing customer ID for updates. If provided, the endpoint will update the customer with this ID.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the operation was successful
</ResponseField>

<ResponseField name="telemetronCustomerId" type="string">
  The unique identifier for the customer
</ResponseField>

<ResponseField name="message" type="string">
  Description of the operation result
</ResponseField>

## Examples

### Create Customer

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://admin.telemetron.ai/api/ext-v1/customer/createOrUpdateCustomer \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "address": "123 Main St, City, State 12345"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://admin.telemetron.ai/api/ext-v1/customer/createOrUpdateCustomer', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'John Doe',
      email: 'john.doe@example.com',
      phone: '+1234567890',
      address: '123 Main St, City, State 12345'
    })
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/customer/createOrUpdateCustomer',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'John Doe',
          'email': 'john.doe@example.com',
          'phone': '+1234567890',
          'address': '123 Main St, City, State 12345'
      }
  )

  data = response.json()
  ```
</CodeGroup>

### Update Customer

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://admin.telemetron.ai/api/ext-v1/customer/createOrUpdateCustomer \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "telemetronCustomerId": "customer-uuid-123",
      "name": "John Doe Updated",
      "email": "john.doe@example.com",
      "phone": "+1234567890"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://admin.telemetron.ai/api/ext-v1/customer/createOrUpdateCustomer', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      telemetronCustomerId: 'customer-uuid-123',
      name: 'John Doe Updated',
      email: 'john.doe@example.com',
      phone: '+1234567890'
    })
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/customer/createOrUpdateCustomer',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'telemetronCustomerId': 'customer-uuid-123',
          'name': 'John Doe Updated',
          'email': 'john.doe@example.com',
          'phone': '+1234567890'
      }
  )

  data = response.json()
  ```
</CodeGroup>

### Response

<CodeGroup>
  ```json Success - Created theme={null}
  {
    "success": true,
    "telemetronCustomerId": "cust_a1b2c3d4e5f6",
    "message": "Customer created successfully"
  }
  ```

  ```json Success - Updated theme={null}
  {
    "success": true,
    "telemetronCustomerId": "cust_a1b2c3d4e5f6",
    "message": "Customer updated successfully"
  }
  ```

  ```json Error - Already Exists theme={null}
  {
    "error": "Customer already exists with this email. Specify telemetronCustomerId to update fields.",
    "telemetronCustomerId": "cust_a1b2c3d4e5f6"
  }
  ```

  ```json Error - Invalid JSON Payload theme={null}
  {
    "error": "Invalid JSON payload"
  }
  ```

  ```json Error - Not Found theme={null}
  {
    "error": "Customer not found or does not belong to this organization"
  }
  ```
</CodeGroup>

<RequestExample>
  ```bash cURL - Create Customer theme={null}
  curl -X POST https://admin.telemetron.ai/api/ext-v1/customer/createOrUpdateCustomer \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "address": "123 Main St, City, State 12345"
    }'
  ```

  ```bash cURL - Update Customer theme={null}
  curl -X POST https://admin.telemetron.ai/api/ext-v1/customer/createOrUpdateCustomer \
    -H "x-api-key: your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "telemetronCustomerId": "customer-uuid-123",
      "name": "John Doe Updated",
      "email": "john.doe@example.com",
      "phone": "+1234567890"
    }'
  ```

  ```javascript JavaScript - Create Customer theme={null}
  const response = await fetch('https://admin.telemetron.ai/api/ext-v1/customer/createOrUpdateCustomer', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'John Doe',
      email: 'john.doe@example.com',
      phone: '+1234567890',
      address: '123 Main St, City, State 12345'
    })
  });

  const data = await response.json();
  ```

  ```javascript JavaScript - Update Customer theme={null}
  const response = await fetch('https://admin.telemetron.ai/api/ext-v1/customer/createOrUpdateCustomer', {
    method: 'POST',
    headers: {
      'x-api-key': 'your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      telemetronCustomerId: 'customer-uuid-123',
      name: 'John Doe Updated',
      email: 'john.doe@example.com',
      phone: '+1234567890'
    })
  });

  const data = await response.json();
  ```

  ```python Python - Create Customer theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/customer/createOrUpdateCustomer',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'name': 'John Doe',
          'email': 'john.doe@example.com',
          'phone': '+1234567890',
          'address': '123 Main St, City, State 12345'
      }
  )

  data = response.json()
  ```

  ```python Python - Update Customer theme={null}
  import requests

  response = requests.post(
      'https://admin.telemetron.ai/api/ext-v1/customer/createOrUpdateCustomer',
      headers={
          'x-api-key': 'your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={
          'telemetronCustomerId': 'customer-uuid-123',
          'name': 'John Doe Updated',
          'email': 'john.doe@example.com',
          'phone': '+1234567890'
      }
  )

  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Success - Created theme={null}
  {
    "success": true,
    "telemetronCustomerId": "cust_a1b2c3d4e5f6",
    "message": "Customer created successfully"
  }
  ```

  ```json Success - Updated theme={null}
  {
    "success": true,
    "telemetronCustomerId": "cust_a1b2c3d4e5f6",
    "message": "Customer updated successfully"
  }
  ```

  ```json Error - Already Exists theme={null}
  {
    "error": "Customer already exists with this email. Specify telemetronCustomerId to update fields.",
    "telemetronCustomerId": "cust_a1b2c3d4e5f6"
  }
  ```

  ```json Error - Invalid JSON Payload theme={null}
  {
    "error": "Invalid JSON payload"
  }
  ```

  ```json Error - Not Found theme={null}
  {
    "error": "Customer not found or does not belong to this organization"
  }
  ```
</ResponseExample>

## Status Codes

| Code | Description                                                                        |
| ---- | ---------------------------------------------------------------------------------- |
| 200  | Customer created or updated successfully                                           |
| 400  | Invalid request (missing required fields, invalid JSON payload, or invalid format) |
| 401  | Invalid or missing API key                                                         |
| 404  | Customer not found (when updating with telemetronCustomerId)                       |
| 409  | Customer already exists with the provided email                                    |
| 500  | Internal server error                                                              |