Create Customer - Devdraft API Documentation

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 Details

method

string

POST

url

string

/api/v0/customers

Authentication: Required (API Key & Secret)
Idempotency: Supported (recommended for customer creation)
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 prevent duplicate customer creation:

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

Request Parameters

Required Parameters

first_name

string

required

Customer’s first name for personalization and legal documentation
Constraints: 1-100 characters
Example: "John"

last_name

string

required

Customer’s last name for personalization and legal documentation
Constraints: 1-100 characters
Example: "Doe"

phone_number

string

required

Customer’s phone number with country code for notifications
Constraints: Max 20 characters, valid format
Example: "+1-555-123-4567"

Optional Parameters

string

Customer’s email address for notifications and receipts
Constraints: Valid email format, max 255 characters
Example: "john.doe@example.com"

customer_type

enum

Type of customer account affecting features and compliance
Values: "Individual", "Startup", "Small Business", "Medium Business", "Enterprise", "Non-Profit", "Government"
Default: "Individual"
Example: "Business"

status

enum

Current status controlling access to services
Values: "ACTIVE", "BLACKLISTED", "DEACTIVATED"
Default: "ACTIVE"
Example: "ACTIVE"

Customer Types

The customer_type field accepts the following values:

Type	Description
Individual	Personal customer account (default)
Startup	Early-stage business customer
Small Business	Small business customer
Medium Business	Medium-sized business customer
Enterprise	Enterprise-level customer
Non-Profit	Non-profit organization
Government	Government entity

Customer Status Values

The status field accepts these enum values:

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

Request Examples

curl -X POST "https://api.devdraft.ai/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: $(uuidgen)" \
  -d '{
    "first_name": "John",
    "last_name": "Doe", 
    "phone_number": "+1-555-123-4567"
  }'

Response Format

Success Response (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

string

Unique customer identifier (UUID)

first_name

string

Customer’s first name

last_name

string

Customer’s last name

string | null

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 | null

Date of last purchase (nullable)

appId

string

Associated application ID

createdAt

string

Customer creation timestamp (ISO 8601)

updatedAt

string

Last update timestamp (ISO 8601)

Error Responses

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

Validation Rules

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 Logic

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)

Use Cases

1. E-commerce Registration

2. Subscription Services

Store customer information for recurring payments and billing cycles.

3. B2B Transactions

Create business customers with appropriate types for enterprise features.

4. International Business

Support customers from different countries with proper phone number formats.

5. Customer Relationship Management

Build comprehensive customer profiles for personalized experiences.

Best Practices

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.

Integration Examples

class CustomerRegistration {
  constructor(api) {
    this.api = api;
  }

  async registerWithValidation(customerData) {
    // Step 1: Validate data
    const validation = await this.api.validateCustomerData(customerData);
    if (!validation.valid) {
      throw new Error(`Validation failed: ${validation.errors.join(', ')}`);
    }

    // Step 2: Check for existing customer
    try {
      const existingCustomer = await this.checkExistingCustomer(customerData.email);
      if (existingCustomer) {
        return { 
          success: false, 
          message: 'Customer already exists',
          customer: existingCustomer 
        };
      }
    } catch (error) {
      // Customer doesn't exist, continue with creation
    }

    // Step 3: Create customer
    try {
      const customer = await this.api.createCustomer(customerData);
      return { 
        success: true, 
        customer 
      };
    } catch (error) {
      return { 
        success: false, 
        message: error.message 
      };
    }
  }

  async checkExistingCustomer(email) {
    // This would typically use the list customers endpoint
    // with email filter to check for duplicates
    return null; // Placeholder
  }

  async bulkCreateCustomers(customers) {
    const results = [];
    for (const customerData of customers) {
      try {
        const result = await this.registerWithValidation(customerData);
        results.push({ 
          data: customerData, 
          result 
        });
      } catch (error) {
        results.push({ 
          data: customerData, 
          error: error.message 
        });
      }
    }
    return results;
  }
}

List Customers - Get customers with filtering
Fetch Customer - Get specific customer details
Update Customer - Update customer information
Blacklist Customer - Blacklist customer access
Delete Customer - Remove customer records

Support

For technical support or questions about customer management:

Review error responses for specific guidance
Check validation rules for data format requirements
Contact support with your application ID and customer ID for faster assistance
Monitor rate limits to avoid throttling

For more information, see:

Home

Customers

Payment Links

Payment Intents

Products

Invoices

Taxes

Webhooks

Wallets

Transfers

​Endpoint Details

​Authentication

​Idempotency

​Request Parameters

​Required Parameters

​Optional Parameters

​Customer Types

​Customer Status Values

​Request Examples

​Response Format

​Success Response (201 Created)

​Response Fields

​Error Responses

​Validation Rules

​Phone Number Format

​Email Validation

​Name Validation

​Business Logic

​Duplicate Prevention

​Default Values

​Audit Trail

​Use Cases

​1. E-commerce Registration

​2. Subscription Services

​3. B2B Transactions

​4. International Business

​5. Customer Relationship Management

​Best Practices

​1. Use Idempotency Keys

​2. Validate Data Client-Side

​3. Handle Duplicates Gracefully

​4. Store Customer IDs

​5. International Support

​6. Privacy Compliance

​Integration Examples

​Related Endpoints

​Support

Endpoint Details

Authentication

Idempotency

Request Parameters

Required Parameters

Optional Parameters

Customer Types

Customer Status Values

Request Examples

Response Format

Success Response (201 Created)

Response Fields

Error Responses

Validation Rules

Phone Number Format

Email Validation

Name Validation

Business Logic

Duplicate Prevention

Default Values

Audit Trail

Use Cases

1. E-commerce Registration

2. Subscription Services

3. B2B Transactions

4. International Business

5. Customer Relationship Management

Best Practices

1. Use Idempotency Keys

2. Validate Data Client-Side

3. Handle Duplicates Gracefully

4. Store Customer IDs

5. International Support

6. Privacy Compliance

Integration Examples

Related Endpoints

Support