Update Customer

Endpoint DetailsCopied!

• Method: PATCH

• URL: /api/v0/customers/{id}

• Content Type: application/json

• Authentication: Required (x-client-key and x-client-secret)

• Rate Limiting: Subject to standard API rate limits

Path ParametersCopied!

Request HeadersCopied!

Content-Type: application/json
x-client-key: your_client_key_here
x-client-secret: your_client_secret_here
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Request Body SchemaCopied!

All fields are optional for updates. Only include the fields you want to modify:

{
  "first_name": "string",          // Optional
  "last_name": "string",           // Optional  
  "phone_number": "string",        // Optional
  "email": "string",               // Optional
  "customer_type": "string",       // Optional
  "status": "CustomerStatus"       // Optional
}

Field Descriptions

Customer Types

• "Individual" - Personal customer account

• "Business" - Business customer account

• "Enterprise" - Enterprise-level customer

• "Non-Profit" - Non-profit organization

Customer Status Values

• "ACTIVE" - Customer can access all services

• "BLACKLISTED" - Customer is blocked from services

• "DEACTIVATED" - Customer account is deactivated

Example RequestsCopied!

Update Customer Name

{
  "first_name": "Jonathan",
  "last_name": "Smith"
}

Update Email and Status

{
  "email": "jonathan.smith@newcompany.com",
  "customer_type": "Business"
}

Deactivate Customer

{
  "status": "DEACTIVATED"
}

Blacklist Customer

{
  "status": "BLACKLISTED"
}

Comprehensive Update

{
  "first_name": "Jonathan",
  "last_name": "Smith",
  "email": "j.smith@enterprise.com",
  "phone_number": "+1-555-999-8888", 
  "customer_type": "Enterprise",
  "status": "ACTIVE"
}

Success ResponseCopied!

Status Code:

200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "Jonathan",
  "last_name": "Smith", 
  "email": "j.smith@enterprise.com",
  "phone_number": "+1-555-999-8888",
  "customer_type": "Enterprise",
  "status": "ACTIVE",
  "last_spent": 0,
  "last_purchase_date": null,
  "appId": "app_123456789",
  "app_id": "app_123456789",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:45:00Z",
  "app": {
    "id": "app_123456789",
    "app_name": "My Application"
  }
}

Response Fields

Error ResponsesCopied!

Customer Not Found (404)

{
  "statusCode": 404,
  "message": "Customer with this ID does not exist",
  "error": "Not Found"
}

Validation Errors (400)

{
  "statusCode": 400,
  "message": [
    "Please provide a valid email address",
    "Phone number cannot exceed 20 characters",
    "First name cannot exceed 100 characters"
  ],
  "error": "Bad Request"
}

Duplicate Email (400)

{
  "statusCode": 400,
  "message": "Customer with this email already exists",
  "error": "Bad Request"
}

Authentication Error (401)

{
  "statusCode": 401,
  "message": "Invalid API credentials",
  "error": "Unauthorized"
}

Rate Limit Exceeded (429)

{
  "statusCode": 429,
  "message": "Too many requests",
  "error": "Too Many Requests"
}

Business LogicCopied!

Partial Updates

• Only fields included in the request body will be updated

• Omitted fields remain unchanged

• Empty string values will update the field to empty (not recommended for required fields)

Email Uniqueness

• Email addresses must be unique within your application scope

• System checks for existing emails before updating

• Customer can update to the same email they already have

Status Changes

• Status changes are tracked with special audit trail entries

• Changing status to BLACKLISTED creates a blacklist audit event

• Changing from BLACKLISTED to ACTIVE creates a removal audit event

Audit Trail

Every customer update is automatically logged with:

• User who made the change

• Timestamp of the change

• Before and after values

• Specific fields that were changed

• Request metadata (IP, user agent)

Validation RulesCopied!

Phone Number Format

• Must include country code when updating

• Accepts numbers, spaces, hyphens, and parentheses

• Maximum 20 characters

• Examples: +1-555-123-4567, +44 20 7946 0958

Email Validation

• Must be valid email format when provided

• Maximum 255 characters

• Case-insensitive storage

• Must be unique per application

Name Validation

• 1-100 characters each when provided

• Cannot be empty strings

• Leading/trailing spaces automatically trimmed

Integration ExamplesCopied!

cURL - Update Name

curl -X PATCH https://api.devdraft.com/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: 550e8400-e29b-41d4-a716-446655440001" \
  -d '{
    "first_name": "Jonathan",
    "last_name": "Smith"
  }'

cURL - Update Status

curl -X PATCH https://api.devdraft.com/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: 550e8400-e29b-41d4-a716-446655440002" \
  -d '{
    "status": "BLACKLISTED"
  }'

JavaScript/Node.js

const customerId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://api.devdraft.com/api/v0/customers/${customerId}`, {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'x-client-key': process.env.DEVDRAFT_CLIENT_KEY,
    'x-client-secret': process.env.DEVDRAFT_CLIENT_SECRET,
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({
    email: 'newemail@example.com',
    customer_type: 'Enterprise'
  })
});

const updatedCustomer = await response.json();
console.log('Updated customer:', updatedCustomer.id);

Python

import requests
import uuid

customer_id = '550e8400-e29b-41d4-a716-446655440000'

response = requests.patch(
    f'https://api.devdraft.com/api/v0/customers/{customer_id}',
    headers={
        'Content-Type': 'application/json',
        'x-client-key': os.getenv('DEVDRAFT_CLIENT_KEY'),
        'x-client-secret': os.getenv('DEVDRAFT_CLIENT_SECRET'),
        'Idempotency-Key': str(uuid.uuid4())
    },
    json={
        'phone_number': '+1-555-999-8888',
        'status': 'ACTIVE'
    }
)

updated_customer = response.json()
print(f"Updated customer: {updated_customer['id']}")

PHP

<?php
$customerId = '550e8400-e29b-41d4-a716-446655440000';

$data = [
    'first_name' => 'Jonathan',
    'customer_type' => 'Business'
];

$options = [
    'http' => [
        'header' => [
            'Content-Type: application/json',
            'x-client-key: ' . $_ENV['DEVDRAFT_CLIENT_KEY'],
            'x-client-secret: ' . $_ENV['DEVDRAFT_CLIENT_SECRET'],
            'Idempotency-Key: ' . uniqid()
        ],
        'method' => 'PATCH',
        'content' => json_encode($data)
    ]
];

$context = stream_context_create($options);
$result = file_get_contents("https://api.devdraft.com/api/v0/customers/{$customerId}", false, $context);
$customer = json_decode($result, true);

echo "Updated customer: " . $customer['id'];
?>

Common Use CasesCopied!

1. Customer Profile Updates

Allow customers to update their own information through your application:

{
  "first_name": "Updated Name",
  "email": "new.email@example.com",
  "phone_number": "+1-555-new-number"
}

2. Account Type Upgrades

Upgrade customers from Individual to Business accounts:

{
  "customer_type": "Business"
}

3. Account Management

Deactivate or reactivate customer accounts:

{
  "status": "DEACTIVATED"
}

4. Fraud Prevention

Blacklist suspicious customers:

{
  "status": "BLACKLISTED"
}

5. Data Corrections

Fix incorrect customer information:

{
  "first_name": "Corrected",
  "last_name": "Name",
  "email": "correct.email@example.com"
}

Best PracticesCopied!

1. Use Idempotency Keys

Always include idempotency keys to prevent duplicate updates during retries.

2. Validate Before Update

Implement client-side validation to reduce API calls and improve user experience.

3. Handle Partial Updates

Only send fields that actually changed to minimize data transfer and audit noise.

4. Check Permissions

Ensure users can only update customers they have permission to modify.

5. Status Change Notifications

Consider notifying customers when their account status changes.

6. Audit Trail Monitoring

Monitor audit trails for suspicious update patterns or unauthorized changes.

7. Backup Before Bulk Updates

When updating many customers, ensure you can revert changes if needed.

Security ConsiderationsCopied!

• Authentication Required: All requests must include valid API credentials

• Application Scope: Customers can only be updated within your application scope

• Audit Logging: All updates are logged with user information and timestamps

• Rate Limiting: Prevent abuse with built-in rate limiting

• Input Validation: All input is validated before processing

Related EndpointsCopied!

• POST /api/v0/customers - Create new customers

• GET /api/v0/customers - List customers with filtering

• GET /api/v0/customers/{id} - Get specific customer details

• POST /api/v0/customers/{id}/liquidation_addresses - Create customer liquidation addresses

SupportCopied!

For technical support or questions about customer updates:

• Review error responses for specific guidance

• Check audit trails for update history

• Contact support with your application ID and customer ID for faster assistance