Create Client

Create a new client record with contact information, addresses, banking details, and preferences.

POST /datatable-clients
Basic Contact Fields
Field Type Required Description
first_name string No Client first name
last_name string No Client last name
company string No Company name
position_company string No Position in company
name_prefix string No Salutation (Mr., Mrs., Dr., etc.)
override_salutation string No Custom salutation override
email string No* Primary email address (*required for most operations)
secondary_email string No Secondary email address
phone string No Phone number
primary_phone string No Primary phone number
office_phone string No Office phone number
mobile string No Mobile number
fax string No Fax number
birthdate integer No Birth date (timestamp in milliseconds)
client_website string No Client website URL
website_language string No Preferred website language code
Address & Location
Field Type Description
address object Creates/updates default address. See address structure below.
Status & Organization
Field Type Description
published boolean Publication status (0 or 1)
agent integer Agent user ID
responsible_user array Array of responsible user IDs
categories array Array of category term IDs or labels
interested_in array Array of interest term IDs or labels
tags array Array of tag term IDs or labels
source integer/string Client source term ID or label
Banking & Financial
Field Type Description
bank_details array Array of bank account objects (multifield). See bank details structure below.
default_payment_method string Default payment method
invoice_release_limit integer Invoice release limit (in cents)
consignor_commissions array Array of commission objects (multifield)
additional_charges array Array of additional charge objects (multifield)
Tax Information
Field Type Description
tax_type string Tax type classification
tax_id string Tax identification number
tax_state string Tax state/region
Instructions & Notes
Field Type Description
billing_instructions string Internal billing instructions
client_billing_instruction string Client-facing billing instructions
shipping_instructions string Internal shipping instructions
shipping_instructions_client string Client-facing shipping instructions
temp_shipping_instructions string Temporary shipping instructions
temp_si_dates_from integer Temporary instructions start date (milliseconds)
temp_si_dates_to integer Temporary instructions end date (milliseconds)
blocking_reason string Reason for blocking client
warning string Warning message about client
Other Fields
Field Type Description
block_emails boolean Block email communications (0 or 1)
subscription_type string Subscription type (email, print, both)
expiration_date integer Account expiration date (milliseconds)
philaworksplace_id string Customer number / PhilaWorksPlace ID
external_ids array Array of external ID objects (multifield)
uuid string Unique identifier (upsert: create if not exists, update if exists)
Address Structure
{
  "address": {
    "country": "US",
    "thoroughfare": "123 Main Street",
    "premise": "Apt 4B",
    "locality": "New York",
    "administrative_area": "NY",
    "postal_code": "10001",
    "name_line": "Jane Smith"
  }
}
Bank Details Structure (Multifield)
{
  "bank_details": [
    {
      "name": "Bank of America",
      "code": "BOFA",
      "number": "123456789",
      "owner": "Jane Smith",
      "iban": "GB82 WEST 1234 5698 7654 32",
      "bic": "BOFAUS3N"
    }
  ]
}
Example Request - Basic Client
{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@example.com",
  "phone": "+1-555-0199",
  "mobile": "+1-555-0200",
  "published": 1,
  "categories": ["10", "15"],
  "subscription_type": "email",
  "address": {
    "country": "US",
    "thoroughfare": "456 Oak Avenue",
    "locality": "Boston",
    "administrative_area": "MA",
    "postal_code": "02101"
  }
}
Example Request - Complete Client with Banking
{
  "first_name": "Robert",
  "last_name": "Johnson",
  "company": "Johnson Collectibles",
  "position_company": "Owner",
  "email": "robert@johnsoncollectibles.com",
  "secondary_email": "robert.personal@example.com",
  "phone": "+1-555-0300",
  "mobile": "+1-555-0301",
  "published": 1,
  "categories": ["Stamps", "Coins"],
  "interested_in": ["European", "Asian"],
  "tags": ["VIP", "Consignor"],
  "tax_type": "business",
  "tax_id": "12-3456789",
  "bank_details": [
    {
      "name": "Chase Bank",
      "number": "987654321",
      "owner": "Robert Johnson",
      "iban": "GB29 NWBK 6016 1331 9268 19",
      "bic": "NWBKGB2L"
    }
  ],
  "billing_instructions": "Net 30 payment terms",
  "shipping_instructions": "Hold all shipments for pickup",
  "responsible_user": [5, 12],
  "address": {
    "country": "US",
    "thoroughfare": "789 Business Blvd",
    "locality": "San Francisco",
    "administrative_area": "CA",
    "postal_code": "94102",
    "name_line": "Johnson Collectibles"
  }
}
Response
{
  "data": [{
    "id": "456",
    "uuid": "abc-def-456",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "philaworksplace_id": "C12348",
    "status": {
      "id": "new",
      "label": "New"
    },
    "balance": {
      "value": 0,
      "formatted": "$0.00"
    },
    "default_address_nid": "789",
    "created": "2025-10-30T10:00:00Z",
    "updated": "2025-10-30T10:00:00Z"
  }]
}
Upsert Behavior

When creating a client with a uuid field:

  • If a client with that UUID exists, it will be updated
  • If no client with that UUID exists, a new client will be created
  • This allows sync operations to safely create or update without checking existence first
Notes
  • Dates are in milliseconds (JavaScript timestamps)
  • Monetary values are in cents (divide by 100 for dollar amounts)
  • Taxonomy terms can be sent as IDs (integers) or labels (strings)
  • The label field is auto-generated and read-only
  • Creating a client with address will automatically create a default address
  • Use separate Client Address endpoint for managing additional addresses
  • Multifield arrays allow multiple entries (e.g., multiple bank accounts)
  • Client access is restricted in token mode - only self-updates allowed
Managing Client Addresses

While you can set the default address during client creation using the address field, additional addresses should be managed using the Client Address endpoint:

Back to Clients Back to API Home