Create Customer

The Create Customer endpoint enables you to create and manage customer records in the Devdraft platform. Customers are core entities that can make payments, receive invoices, and interact with your payment links and products. This endpoint provides secure customer data management with built-in validation and audit trails.

Endpoint DetailsCopied!

Method: POST
URL: /api/v0/customers
Content Type: application/json
Authentication: Required (x-client-key and x-client-secret)
Rate Limiting: Subject to standard API rate limits

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!

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

Field Descriptions

Field	Type	Required	Description	Constraints
`first_name`	string	✅	Customer's first name for personalization and legal documentation	1-100 characters
`last_name`	string	✅	Customer's last name for personalization and legal documentation	1-100 characters
`phone_number`	string	✅	Customer's phone number with country code for notifications	Max 20 characters, valid format
`email`	string	❌	Customer's email address for notifications and receipts	Valid email format, max 255 characters
`customer_type`	string	❌	Type of customer account affecting features and compliance	See customer types below
`status`	CustomerStatus	❌	Current status controlling access to services	Default: `ACTIVE`

Customer Types

The customer_type field accepts the following values:

"Individual" - Personal customer account (default)
"Business" - Business customer account
"Enterprise" - Enterprise-level customer
"Non-Profit" - Non-profit organization

Customer Status Values

The status field accepts these enum values:

"ACTIVE" - Customer can access all services (default)
"BLACKLISTED" - Customer is blocked from services
"DEACTIVATED" - Customer account is deactivated

Example RequestsCopied!

Minimal Request

{
  "first_name": "John",
  "last_name": "Doe", 
  "phone_number": "+1-555-123-4567"
}

Complete Request

{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@business.com",
  "phone_number": "+1-555-987-6543",
  "customer_type": "Business",
  "status": "ACTIVE"
}

International Customer

{
  "first_name": "Pierre",
  "last_name": "Dubois",
  "email": "pierre@example.fr", 
  "phone_number": "+33-1-42-86-83-26",
  "customer_type": "Individual"
}

Success ResponseCopied!

Status Code:

201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone_number": "+1-555-123-4567",
  "customer_type": "Individual",
  "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-15T10:30:00Z"
}

Response Fields

Field	Type	Description
`id`	string	Unique customer identifier (UUID)
`first_name`	string	Customer's first name
`last_name`	string	Customer's last name
`email`	string	Customer's email address (nullable)
`phone_number`	string	Customer's phone number
`customer_type`	string	Type of customer account
`status`	string	Current customer status
`last_spent`	number	Last transaction amount (default: 0)
`last_purchase_date`	string	Date of last purchase (nullable)
`appId`	string	Associated application ID
`createdAt`	string	Customer creation timestamp
`updatedAt`	string	Last update timestamp

Error ResponsesCopied!

Validation Errors (400)

{
  "statusCode": 400,
  "message": [
    "First name is required",
    "Please provide a valid email address",
    "Phone number cannot exceed 20 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"
}

Validation RulesCopied!

Phone Number Format

Must include country code (recommended format: +[country-code]-[number])
Accepts numbers, spaces, hyphens, and parentheses
Maximum 20 characters
Examples: +1-555-123-4567, +44 20 7946 0958, +33 1 42 86 83 26

Email Validation

Must be valid email format when provided
Maximum 255 characters
Case-insensitive storage
Must be unique per application

Name Validation

Both first and last names required
1-100 characters each
Cannot be empty strings
Leading/trailing spaces automatically trimmed

Business LogicCopied!

Duplicate Prevention

Email addresses must be unique within your application scope
Phone numbers can be duplicated (multiple customers can share numbers)
System checks for existing emails before creation

Default Values

status defaults to "ACTIVE" if not provided
customer_type defaults to "Individual" if not provided
last_spent initializes to 0
last_purchase_date initializes to null

Audit Trail

Every customer creation is automatically logged with:

User who created the customer
Timestamp of creation
Customer details
Request metadata (IP, user agent)

Integration ExamplesCopied!

cURL

curl -X POST https://api.devdraft.com/api/v0/customers \
  -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-446655440000" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+1-555-123-4567",
    "customer_type": "Individual"
  }'

JavaScript/Node.js

const response = await fetch('https://api.devdraft.com/api/v0/customers', {
  method: 'POST',
  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({
    first_name: 'John',
    last_name: 'Doe',
    email: 'john.doe@example.com',
    phone_number: '+1-555-123-4567',
    customer_type: 'Individual'
  })
});

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

Python

import requests
import uuid

response = requests.post(
    'https://api.devdraft.com/api/v0/customers',
    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={
        'first_name': 'John',
        'last_name': 'Doe',
        'email': 'john.doe@example.com',
        'phone_number': '+1-555-123-4567',
        'customer_type': 'Individual'
    }
)

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

Best PracticesCopied!

1. Use Idempotency Keys

Always include idempotency keys to prevent duplicate customer creation during retries.

2. Validate Data Client-Side

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

3. Handle Duplicates Gracefully

Check for existing customers before creation or handle duplicate email errors appropriately.

4. Store Customer IDs

Save the returned customer ID for future transactions and references.

5. International Support

Always include country codes in phone numbers for proper SMS delivery.

6. Privacy Compliance

Ensure you have proper consent before storing customer data, especially emails.

GET /api/v0/customers - List customers with filtering
GET /api/v0/customers/{id} - Get specific customer details
PATCH /api/v0/customers/{id} - Update customer information
POST /api/v0/customers/{id}/liquidation_addresses - Create liquidation addresses

SupportCopied!

For technical support or questions about customer management:

Review our API documentation
Check error responses for specific guidance
Contact support with your application ID and customer ID for faster assistance