> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usejuiced.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Customer

> Create a customer from your CRM or another tool, and optionally invite them to their portal.

Only `name` and `email` are required, so a CRM workflow can create a customer straight from a contact. Add `send_invite` to email the customer a link to set up their portal login.

Each email can belong to one active customer in your account. An archived customer's email can be used for a new customer. To check whether a contact is already a customer, [look them up by email](https://docs.usejuiced.com/api-reference/endpoint/v1/customers-list.md) first.

Send an `Idempotency-Key` header so a retried request can never create a second customer. See [Safe retries](https://docs.usejuiced.com/api-reference/api-keys.md#safe-retries).


## OpenAPI

````yaml POST /v1/customers
openapi: 3.1.0
info:
  title: Juiced API
  description: >-
    API for submitting pings and leads to Juiced. Build on the v1 endpoints
    under `/v1`. The unversioned `/ping` and `/leads` endpoints are the frozen
    legacy contract and are deprecated.
  version: 1.0.0
servers:
  - url: https://usejuiced.com/api
    description: Production server
security:
  - Basic Auth: []
  - Bearer Token: []
tags:
  - name: v1
    description: The current API. Build on these endpoints.
  - name: Customers
    description: Create and look up your customers with an API key.
  - name: Legacy
    description: The frozen, deprecated unversioned endpoints.
paths:
  /v1/customers:
    post:
      tags:
        - Customers
      summary: Create a customer
      description: >-
        Creates a customer. Only `name` and `email` are required. With
        `send_invite`, the customer is emailed an invite to set up their portal
        login.


        Send an `Idempotency-Key` header so a retry can never create a second
        customer.


        Requires the `customers:write` ability.
      operationId: createCustomerV1
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            maxLength: 255
          description: >-
            Any string, such as your CRM's contact ID. A retry with the same key
            and body within 24 hours returns the original response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequestV1'
            examples:
              Name and email:
                summary: Name and email
                value:
                  name: Acme Roofing
                  email: owner@acme-roofing.com
                  send_invite: true
              With address:
                summary: With address
                value:
                  name: Acme Roofing
                  email: owner@acme-roofing.com
                  phone: 555-123-4567
                  address: 742 Orchard Lane
                  city: Paradise Bay
                  state: FL
                  zip: '33139'
                  country: US
                  can_access_bidding: true
      responses:
        '201':
          description: >-
            Customer created. A retry with the same `Idempotency-Key` and body
            returns this same response again, with an `Idempotent-Replayed:
            true` header.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotent-Replayed:
              description: >-
                Sent as `true` when this is a stored response to a retried
                request.
              schema:
                type: string
                example: 'true'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponseV1'
              example:
                data:
                  id: cus_01jbx8p4r6t8v0x2z4b6d8f0hk
                  name: Acme Roofing
                  email: owner@acme-roofing.com
                  phone: null
                  address: null
                  address_2: null
                  city: null
                  state: null
                  zip: null
                  country: null
                  paused: false
                  can_access_bidding: false
                  can_access_club: false
                  balance: 0
                  daily_lead_cap: null
                  weekly_lead_cap: null
                  monthly_lead_cap: null
                  daily_budget: null
                  weekly_budget: null
                  monthly_budget: null
                  archived_at: null
                  created_at: '2026-11-17T15:04:05Z'
                  updated_at: '2026-11-17T15:04:05Z'
                version: v1
        '401':
          $ref: '#/components/responses/ApiKeyUnauthenticatedV1'
        '403':
          $ref: '#/components/responses/ApiKeyForbiddenV1'
        '409':
          description: >-
            The `Idempotency-Key` was already used and this request can't be
            replayed.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Retry-After:
              description: >-
                Sent with `idempotency_in_progress` only. Seconds to wait before
                retrying the same request.
              schema:
                type: integer
                example: 5
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorV1'
              examples:
                Same key, different body:
                  summary: Same key, different body
                  value:
                    error:
                      code: idempotency_conflict
                      message: >-
                        This Idempotency-Key was already used with a different
                        request body.
                    version: v1
                First request still running:
                  summary: First request still running
                  value:
                    error:
                      code: idempotency_in_progress
                      message: >-
                        A request with this Idempotency-Key is still being
                        processed. Retry after the number of seconds in the
                        Retry-After header.
                    version: v1
        '422':
          description: The customer failed validation.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorV1'
              example:
                error:
                  code: validation_failed
                  message: The email has already been taken.
                  errors:
                    email:
                      - The email has already been taken.
                version: v1
        '429':
          $ref: '#/components/responses/RateLimitedV1'
        '500':
          $ref: '#/components/responses/ServerErrorV1'
      security:
        - API Key: []
components:
  schemas:
    CustomerRequestV1:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
          maxLength: 255
          description: The customer's business or display name.
        email:
          type: string
          format: email
          maxLength: 255
          description: >-
            Must include a domain with a TLD. Unique across your active
            customers. An archived customer's email can be used again.
        phone:
          type: string
          description: A US, Canadian, Australian or Latvian phone number.
        address:
          type: string
          maxLength: 255
        address_2:
          type: string
          maxLength: 255
        city:
          type: string
          maxLength: 255
        state:
          type: string
          maxLength: 255
        zip:
          type: string
          description: Checked against `country`, which is required with it.
        country:
          type: string
          enum:
            - US
            - CA
            - AU
            - LV
          description: Required when `state` or `zip` is sent.
        paused:
          type: boolean
          default: false
        can_access_bidding:
          type: boolean
          default: false
        can_access_club:
          type: boolean
          default: false
        daily_lead_cap:
          type: integer
          minimum: 1
          maximum: 2147483647
          description: >-
            Most leads a day. Accepted only when the matching cap or budget is
            turned on in your account settings, and ignored otherwise.
        weekly_lead_cap:
          type: integer
          minimum: 1
          maximum: 2147483647
          description: >-
            Most leads a week. Accepted only when the matching cap or budget is
            turned on in your account settings, and ignored otherwise.
        monthly_lead_cap:
          type: integer
          minimum: 1
          maximum: 2147483647
          description: >-
            Most leads a month. Accepted only when the matching cap or budget is
            turned on in your account settings, and ignored otherwise.
        daily_budget:
          type: number
          minimum: 1
          maximum: 21474836
          description: >-
            Most spent a day, in dollars. Accepted only when the matching cap or
            budget is turned on in your account settings, and ignored otherwise.
        weekly_budget:
          type: number
          minimum: 1
          maximum: 21474836
          description: >-
            Most spent a week, in dollars. Accepted only when the matching cap
            or budget is turned on in your account settings, and ignored
            otherwise.
        monthly_budget:
          type: number
          minimum: 1
          maximum: 21474836
          description: >-
            Most spent a month, in dollars. Accepted only when the matching cap
            or budget is turned on in your account settings, and ignored
            otherwise.
        send_invite:
          type: boolean
          default: false
          description: Email the customer an invite to set up their portal login.
    CustomerResponseV1:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CustomerV1'
        version:
          type: string
          enum:
            - v1
    ErrorV1:
      title: Error
      type: object
      required:
        - error
        - version
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - unauthenticated
                - validation_failed
                - quota_reached
                - ping_mismatch
                - idempotency_conflict
                - idempotency_in_progress
                - idempotency_reserved
                - idempotency_version_mismatch
                - rate_limited
                - not_found
                - method_not_allowed
                - bad_request
                - server_error
              description: Machine-readable error code. Branch on this, not on `message`.
            message:
              type: string
              description: Human-readable explanation.
            errors:
              type: object
              description: Only with `validation_failed`. Messages keyed by field.
              additionalProperties:
                type: array
                items:
                  type: string
            lead_id:
              type: string
              pattern: ^lead_[0-9a-z]{26}$
              description: >-
                Only with `idempotency_version_mismatch`. The lead the
                `transaction_id` already created.
        version:
          type: string
          enum:
            - v1
          description: Always `v1`.
    CustomerV1:
      title: Customer
      type: object
      properties:
        id:
          type: string
          pattern: ^cus_[0-9a-z]{26}$
          description: The customer's public ID.
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type:
            - string
            - 'null'
          description: Phone number.
        address:
          type:
            - string
            - 'null'
          description: Street address.
        address_2:
          type:
            - string
            - 'null'
          description: Second address line.
        city:
          type:
            - string
            - 'null'
          description: City.
        state:
          type:
            - string
            - 'null'
          description: State, province or region.
        zip:
          type:
            - string
            - 'null'
          description: Postal code.
        country:
          type:
            - string
            - 'null'
          description: 'Two-letter country code: `US`, `CA`, `AU` or `LV`.'
        paused:
          type: boolean
          description: Whether the customer is paused and gets no leads.
        can_access_bidding:
          type: boolean
          description: Whether the customer can place bids.
        can_access_club:
          type: boolean
          description: Whether the customer can join the Club.
        balance:
          type: number
          description: Available balance in dollars, after funds held for pending pings.
        daily_lead_cap:
          type:
            - integer
            - 'null'
          description: Most leads a day.
        weekly_lead_cap:
          type:
            - integer
            - 'null'
          description: Most leads a week.
        monthly_lead_cap:
          type:
            - integer
            - 'null'
          description: Most leads a month.
        daily_budget:
          type:
            - number
            - 'null'
          description: Most spent a day, in dollars.
        weekly_budget:
          type:
            - number
            - 'null'
          description: Most spent a week, in dollars.
        monthly_budget:
          type:
            - number
            - 'null'
          description: Most spent a month, in dollars.
        archived_at:
          type:
            - string
            - 'null'
          description: When the customer was archived.
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  headers:
    XRequestId:
      description: >-
        Unique ID for this request, sent on every v1 response (errors included).
        Quote it when contacting support.
      schema:
        type: string
        pattern: ^req_[0-9a-z]{26}$
        example: req_01jbx8k6y3a5c7e9g1j3m5p7rt
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        example: 30
  responses:
    ApiKeyUnauthenticatedV1:
      description: The API key is missing, unknown, revoked or expired.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorV1'
          example:
            error:
              code: unauthenticated
              message: >-
                Missing or invalid API key. Send an active jz_live_ key as a
                bearer token.
            version: v1
    ApiKeyForbiddenV1:
      description: >-
        The key lacks the ability this endpoint needs, your plan doesn't include
        the API, or your account is locked for an unpaid subscription.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorV1'
          examples:
            Missing ability:
              summary: Missing ability
              value:
                error:
                  code: bad_request
                  message: This API key does not have the customers:write ability.
                version: v1
            Plan without the API:
              summary: Plan without the API
              value:
                error:
                  code: bad_request
                  message: >-
                    The API is not included in your plan. Upgrade to a paid plan
                    to use it.
                version: v1
            Account locked:
              summary: Account locked
              value:
                error:
                  code: bad_request
                  message: This workspace is locked until its subscription is paid.
                version: v1
    RateLimitedV1:
      description: Too many requests.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorV1'
          example:
            error:
              code: rate_limited
              message: >-
                Too many requests. Retry after the number of seconds in the
                Retry-After header.
            version: v1
    ServerErrorV1:
      description: >-
        Something went wrong on our side. Quote the `X-Request-Id` header when
        contacting support.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorV1'
          example:
            error:
              code: server_error
              message: >-
                An unexpected error occurred. Quote the X-Request-Id header when
                contacting support.
            version: v1
  securitySchemes:
    Basic Auth:
      type: http
      scheme: basic
      description: >-
        Use your source's API key as the username and API secret as the
        password. Base64 encode the credentials in the format
        `api_key:api_secret`.
    Bearer Token:
      type: http
      scheme: bearer
      description: Use a bearer token generated for your source.
    API Key:
      type: http
      scheme: bearer
      description: >-
        An API key from **Configure → API Keys** (it starts with `jz_live_`),
        sent as a bearer token. See [API Keys](/api-reference/api-keys).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.