---
key: create-customers-and-leads-with-the-api
title: Create customers and leads through the API
audience: developer
section: api/getting-started
routes: []
since: 0.0.1
updated: 0.0.1
status: published
summary: Choose the right permissions and lifecycle, then create an account with contacts, methods and locations in one retry-safe request.
keywords: [create customer, create lead, add account, API key, atomic, external identity, import]
related: [create-an-api-key-for-your-own-software, api-reference, api-record-identity, api-errors]
---

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]].

```json
{
  "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:

```json
{
  "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.