{
  "id": "cust_123456",
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@newcompany.com",
  "phone_number": "+1-987-654-3210",
  "customer_type": "Enterprise",
  "status": "ACTIVE",
  "last_spent": 1250.50,
  "last_purchase_date": "2024-03-15T14:30:00Z",
  "appId": "app_789012",
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-22T14:15:30Z"
}
The Update Customer endpoint allows you to modify existing customer information with flexible field-level updates. This endpoint supports partial updates, meaning you only need to include the fields you want to change. It provides comprehensive validation, audit logging, and maintains data integrity while allowing for customer profile management and corrections.

​
Endpoint Details

​
method
string
PATCH
​
url
string
/api/v0/customers/{id}
Authentication: Required (API Key & Secret)
Idempotency: Supported (recommended for updates)
Rate Limiting: Subject to standard API rate limits

​
Authentication

All requests require API key authentication using the following headers:
  • x-client-key: Your application’s client key
  • x-client-secret: Your application’s client secret

​
Idempotency

Include an idempotency key to ensure update operations are safely retryable:
  • idempotency-key: Include a unique UUID v4 in the header
  • Subsequent requests with the same key return the original response
  • Keys expire after 24 hours

​
Path Parameters

​
id
string
required
Customer’s unique identifier (UUID)
Format: UUID v4
Example: "550e8400-e29b-41d4-a716-446655440000"

​
Request Parameters

All parameters are optional - include only the fields you want to update.

​
Basic Information

​
first_name
string
Customer’s first name
Constraints: 1-100 characters
Example: "John"
​
last_name
string
Customer’s last name
Constraints: 1-100 characters
Example: "Smith"
​
phone_number
string
Customer’s phone number with country code
Constraints: Max 20 characters, valid format
Example: "+1-987-654-3210"
​
email
string
Customer’s email address
Constraints: Valid email format, max 255 characters, must be unique
Example: "john.smith@newcompany.com"

​
Account Settings

​
customer_type
enum
Type of customer account
Values: "Individual", "Startup", "Small Business", "Medium Business", "Enterprise", "Non-Profit", "Government"
Example: "Enterprise"
​
status
enum
Customer account status
Values: "ACTIVE", "BLACKLISTED", "DEACTIVATED"
Example: "ACTIVE"
Note: Status changes may require additional verification

​
Request Examples

curl -X PATCH "https://api.devdraft.ai/api/v0/customers/550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{
    "phone_number": "+1-987-654-3210",
    "email": "john.smith@newcompany.com"
  }'

​
Response Format

​
Success Response (200 OK)

{
  "id": "cust_123456",
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@newcompany.com",
  "phone_number": "+1-987-654-3210",
  "customer_type": "Enterprise",
  "status": "ACTIVE",
  "last_spent": 1250.50,
  "last_purchase_date": "2024-03-15T14:30:00Z",
  "appId": "app_789012",
  "createdAt": "2024-03-20T10:00:00Z",
  "updatedAt": "2024-03-22T14:15:30Z"
}

​
Response Fields

​
id
string
Unique customer identifier (unchanged)
​
first_name
string
Updated first name
​
last_name
string
Updated last name
​
email
string | null
Updated email address
​
phone_number
string
Updated phone number
​
customer_type
string
Updated customer type
​
status
string
Updated customer status
​
last_spent
number
Last transaction amount (unchanged)
​
last_purchase_date
string | null
Last purchase date (unchanged)
​
appId
string
Associated application ID (unchanged)
​
createdAt
string
Customer creation timestamp (unchanged)
​
updatedAt
string
Updated timestamp reflecting the modification

​
Error Responses

{
  "statusCode": 400,
  "message": [
    "First name cannot be empty",
    "Invalid email format",
    "Phone number cannot exceed 20 characters"
  ],
  "error": "Bad Request"
}

​
Business Logic

​
Partial Updates

  • Only include fields you want to update
  • Unchanged fields retain their current values
  • Empty string values are treated as clearing the field (where applicable)

​
Email Uniqueness

  • Email addresses must be unique within your application scope
  • Updating to an existing email will result in a 409 Conflict error
  • Setting email to null or empty string clears the email field

​
Status Changes

  • Status changes are logged for audit purposes
  • Some status changes may trigger additional business logic
  • Changing from BLACKLISTED to ACTIVE may require additional verification

​
Automatic Fields

  • updatedAt is automatically set to the current timestamp
  • id, createdAt, and transaction-related fields cannot be modified
  • appId remains unchanged and scoped to your application

​
Use Cases

​
1. Profile Updates

Allow customers to update their own profile information through your application.

​
2. Administrative Corrections

Customer service representatives can correct customer information.

​
3. Account Upgrades

Update customer type when business accounts upgrade their service level.

​
4. Status Management

Manage customer access by updating their account status.

​
5. Data Migration

Bulk update customer records during data migration or cleanup operations.

​
Best Practices

​
1. Validate Before Updating

Always validate data client-side before making API calls to reduce errors.

​
2. Use Idempotency Keys

Include idempotency keys for update operations to ensure safe retries.

​
3. Handle Conflicts Gracefully

Implement proper handling for email uniqueness conflicts.

​
4. Partial Updates Only

Only send fields that actually need to be updated to minimize conflicts.

​
5. Audit Trail

Log customer updates in your application for audit and compliance purposes.

​
6. Status Change Notifications

Notify customers when their account status changes significantly.

​
Support

For technical support or questions about updating customers:
  • Ensure customer ID is a valid UUID v4 format
  • Check validation rules for field constraints
  • Verify email uniqueness before updates
  • Contact support with specific customer IDs that cause issues
For more information, see: