Customers

Sync your customer base with SupportDesk. The customer is identified by its externalId — your identifier (user ID in your DB, UUID, etc.), not a SupportDesk ID.

Endpoint

PATCH /customers/:externalId

Upsert behavior: creates if it doesn’t exist, updates otherwise.

Body

Field	Type	Required on create	Description
email	string	✅	Customer email — unique per app
name	string	✅	Display name
phone	string	—	Phone number
avatarUrl	string (URL)	—	Avatar URL
metadata	object	—	Free-form data (plan, companyName, etc.)

On create, email and name are required. On update, all fields are optional — only provided ones are changed.

Example — create

curl

curl -X PATCH https://supportdesk.innovartx.com/api/v1/customers/user_42 \
  -H "X-API-Key: $SUPPORTDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john@acme.com",
    "name": "John Doe",
    "phone": "+1 555 0100",
    "metadata": { "plan": "premium", "companyName": "Acme" }
  }'

Node.js

await fetch('https://supportdesk.innovartx.com/api/v1/customers/user_42', {
  method: 'PATCH',
  headers: {
    'X-API-Key': process.env.SUPPORTDESK_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'john@acme.com',
    name: 'John Doe',
    phone: '+1 555 0100',
    metadata: { plan: 'premium', companyName: 'Acme' },
  }),
});

Python (requests)

import os, requests

requests.patch(
    'https://supportdesk.innovartx.com/api/v1/customers/user_42',
    headers={'X-API-Key': os.environ['SUPPORTDESK_API_KEY']},
    json={
        'email': 'john@acme.com',
        'name': 'John Doe',
        'phone': '+1 555 0100',
        'metadata': {'plan': 'premium', 'companyName': 'Acme'},
    },
)

PHP (curl)

$ch = curl_init('https://supportdesk.innovartx.com/api/v1/customers/user_42');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_POSTFIELDS => json_encode([
        'email' => 'john@acme.com',
        'name' => 'John Doe',
        'phone' => '+1 555 0100',
        'metadata' => ['plan' => 'premium', 'companyName' => 'Acme'],
    ]),
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('SUPPORTDESK_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);

Response

{
  "success": true,
  "data": {
    "customer": {
      "id": "clxxxxxx",
      "externalId": "user_42",
      "email": "john@acme.com",
      "name": "John Doe",
      "phone": "+1 555 0100",
      "metadata": { "plan": "premium", "companyName": "Acme" },
      "createdAt": "2026-04-18T10:00:00Z",
      "updatedAt": "2026-04-18T10:00:00Z"
    },
    "wasCreated": true
  },
  "timestamp": "2026-04-18T10:00:00Z"
}

wasCreated is true on the first request for a given externalId, false on subsequent ones.

Example — partial update

Only the fields sent are changed:

curl

curl -X PATCH https://supportdesk.innovartx.com/api/v1/customers/user_42 \
  -H "X-API-Key: $SUPPORTDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1 555 0199"}'

Errors

HTTP code	Business code	Cause
400	VALIDATION_ERROR	email or name missing on create
409	CUSTOMER_EMAIL_EXISTS	Another customer already has this email in your app

See Errors for full format.