Create customers and leads through the API

Choose the right permissions and lifecycle, then create an account with contacts, methods and locations in one retry-safe request.

In Administration → AI → Outside AI → API keys, create a key and choose the Create customers and leads preset under What it can do. Customers and leads share POST /v1/crm/accounts/; their lifecycle distinguishes them.

Prepare the request

1. Get /v1/lifecycle-statuses/. Choose an enabled status in category pre_active for a lead, or active for a customer. Save your organization's chosen UID; labels and defaults vary by organization. Do not send status: "lead".
2. Get /v1/crm/accounts/address-policy?lifecycle_category=pre_active for a lead, or use active for a customer. Follow the required address categories. An organization can defer lead requirements until activation.
3. Use /v1/crm/accounts/duplicate-check to review possible duplicates. Do not automatically merge records based on names, email addresses or phone numbers.
4. Send an Idempotency-Key with each new creation. After an uncertain network result, retry the identical body and key. Changed content with the same successful key returns 409.

Create atomically

Replace the lifecycle UID below with one returned for your organization. Send your bearer token and X-Organization-ID as described in API reference.

{
  "account_type": "household",
  "display_name": "Jordan Lee",
  "lifecycle_status_id": "lstat_0123456789abcdef",
  "external_ids": [{"namespace": "website-enquiries", "key": "enquiry-739"}],
  "contacts": [{
    "display_name": "Jordan Lee",
    "is_primary": true,
    "methods": [{"method_type": "email", "value": "jordan@example.com"}]
  }],
  "locations": []
}

Use this addressless example only when the returned policy permits it. For required addresses, supply locations using the current location types and address schema in API reference. Each location can also contain methods. Use account_methods for the account's own main email or phone.

For a company customer, choose an active lifecycle UID. This example includes a billing address; add any other categories required by the returned policy:

{
  "account_type": "company",
  "company_name": "Example Services",
  "display_name": "Example Services",
  "lifecycle_status_id": "lstat_fedcba9876543210",
  "account_methods": [{"method_type": "email", "value": "office@example.com"}],
  "locations": [{
    "location_type": "billing",
    "is_primary": true,
    "address_line1": "100 Example Street",
    "city": "Ottawa",
    "region_code": "ON",
    "postal_code": "K1P 1J1",
    "country_code": "CA"
  }]
}

Account details, contacts, locations, their methods, custom fields, external identities and an optional billing_profile save in one transaction. A validation failure saves none of them. Billing selections use zero-based request indexes: new contacts first, then linked contacts; locations follow request order.

The response contains the account uid and human record number. Use UIDs in subsequent calls. Nested methods need crm.contact_methods.create; optional billing defaults need billing.account_profiles.update. Setting po_required also needs billing.account_profiles.receivables.update; tax_exempt needs billing.account_profiles.compliance.update. The starter preset excludes billing changes and updates to existing customers.

Import and convert safely

An external identity is unique within the organization by namespace and key. A second create with the same identity returns 409; look up /v1/crm/accounts/external-identity?namespace=website-enquiries&key=enquiry-739, then explicitly update the returned account if appropriate. This uniqueness survives the retry-record retention window. Branch access still applies.

To activate a lead, preview and then apply /v1/crm/accounts/{account_uid}/lifecycle-transition using target_lifecycle_status_id. The preview suffix is /preview. Resolve any blocking requirements first.

Creation grants no marketing consent. can_text describes the number's capability. Embedded methods cannot assert verification or consent; verification follows the organization's existing policy.