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

# Submit a Lead

> Submit a complete lead for validation, distribution, and assignment.

If you pinged first, send the ping's `id` as `ping_id`. You can also echo the `bids[].id` you chose as `bid_id`. It's checked, but it doesn't change who gets the lead.

Send a `transaction_id` so a retry can never create a second lead. See [Safe retries](https://docs.usejuiced.com/api-reference/introduction.md#safe-retries) for how retries are answered.


## OpenAPI

````yaml POST /v1/leads
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: Legacy
    description: The frozen, deprecated unversioned endpoints.
paths:
  /v1/leads:
    post:
      tags:
        - v1
      summary: Submit a lead
      description: >-
        Submits a complete lead for processing. The lead is validated, checked
        for duplicates, matched to a lead type, and distributed to a buyer (or
        placed in the marketplace or Club).


        If you pinged first, include the ping's `id` as `ping_id`. You can also
        echo the `bids[].id` you chose as `bid_id`. It's checked, but it doesn't
        change who gets the lead.


        Send a `transaction_id` so a retry can never create a second lead. One
        `transaction_id` is one lead on either API version.
      operationId: createLeadV1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadRequestV1'
            examples:
              Basic lead:
                summary: Basic lead
                value:
                  transaction_id: order-10482
                  first_name: Katy
                  last_name: Berry
                  email: katy.berry@thirstyleads.com
                  phone: 555-123-4567
                  address_1: 742 Orchard Lane
                  city: Paradise Bay
                  state: FL
                  zip: '33139'
              Lead after a ping:
                summary: Lead after a ping
                value:
                  transaction_id: order-10483
                  ping_id: ping_01jbx8k6y2m4n7p9q3r5s8t0vw
                  bid_id: bid_01h9z3c5e7g9j1k3m5n7p9r1st
                  first_name: Brad
                  last_name: Pit
                  email: brad.pit@juiceboxoffice.com
                  phone: 555-987-6543
                  address_1: 100 Citrus Grove Dr
                  city: Tropicana
                  state: CA
                  zip: '90210'
      responses:
        '201':
          description: >-
            Lead received. Check `data.status` for the outcome. A retry with the
            same `transaction_id` and payload returns this same response again.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadResponseV1'
              examples:
                Accepted:
                  summary: Accepted
                  value:
                    data:
                      id: lead_01jbx8m2d4f6g8h0j2k4m6n8pq
                      status: accepted
                      price: 45
                    version: v1
                Rejected:
                  summary: Rejected
                  value:
                    data:
                      id: lead_01jbx8m2d4f6g8h0j2k4m6n8pq
                      status: rejected
                      price: 0
                    version: v1
                Duplicate:
                  summary: Duplicate
                  value:
                    data:
                      id: lead_01jbx8m2d4f6g8h0j2k4m6n8pq
                      status: duplicate
                      price: 0
                    version: v1
        '401':
          $ref: '#/components/responses/UnauthenticatedV1'
        '409':
          description: >-
            The `transaction_id` 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 transaction_id, different payload:
                  summary: Same transaction_id, different payload
                  value:
                    error:
                      code: idempotency_conflict
                      message: >-
                        This transaction_id was already used with a different
                        payload.
                    version: v1
                First attempt still processing:
                  summary: First attempt still processing
                  value:
                    error:
                      code: idempotency_in_progress
                      message: >-
                        This transaction_id is already processing. Retry the
                        same request later.
                    version: v1
                Outcome unconfirmed, do not resubmit:
                  summary: Outcome unconfirmed, do not resubmit
                  value:
                    error:
                      code: idempotency_reserved
                      message: >-
                        This transaction was accepted but its outcome could not
                        be confirmed. It is reserved for review; do not resubmit
                        it.
                    version: v1
                transaction_id first used on the legacy API:
                  summary: transaction_id first used on the legacy API
                  value:
                    error:
                      code: idempotency_version_mismatch
                      message: >-
                        This transaction_id was already used on the legacy API.
                        Retry it on the same API version.
                      lead_id: lead_01jbx8m2d4f6g8h0j2k4m6n8pq
                    version: v1
        '422':
          description: >-
            The lead failed validation, the source reached a lead quota, or the
            lead doesn't match its ping.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorV1'
              examples:
                Validation failed:
                  summary: Validation failed
                  value:
                    error:
                      code: validation_failed
                      message: >-
                        The email field must be a valid email address. (and 1
                        more error)
                      errors:
                        email:
                          - The email field must be a valid email address.
                        zip:
                          - >-
                            The postal code is not valid for this account's
                            operating countries.
                    version: v1
                Ping not found:
                  summary: Ping not found
                  value:
                    error:
                      code: validation_failed
                      message: The ping could not be found.
                      errors:
                        ping_id:
                          - The ping could not be found.
                    version: v1
                Legacy ping UUID sent as ping_id:
                  summary: Legacy ping UUID sent as ping_id
                  value:
                    error:
                      code: validation_failed
                      message: >-
                        The ping id must be the ping_… id returned by
                        /api/v1/ping.
                      errors:
                        ping_id:
                          - >-
                            The ping id must be the ping_… id returned by
                            /api/v1/ping.
                    version: v1
                Ping already used:
                  summary: Ping already used
                  value:
                    error:
                      code: validation_failed
                      message: This ping has already been used.
                      errors:
                        ping_id:
                          - This ping has already been used.
                    version: v1
                Source lead quota reached:
                  summary: Source lead quota reached
                  value:
                    error:
                      code: quota_reached
                      message: This source has reached one of its lead quotas.
                    version: v1
                Lead doesn't match its ping:
                  summary: Lead doesn't match its ping
                  value:
                    error:
                      code: ping_mismatch
                      message: Lead data does not match ping data.
                    version: v1
        '429':
          $ref: '#/components/responses/RateLimitedV1'
        '500':
          $ref: '#/components/responses/ServerErrorV1'
components:
  schemas:
    LeadRequestV1:
      title: Lead Request
      type: object
      required:
        - zip
      properties:
        transaction_id:
          type: string
          maxLength: 255
          description: >-
            Your own ID for this lead, such as an order or lead number. A retry
            with the same `transaction_id` and payload returns the original
            response instead of creating a second lead. Numbers are accepted and
            treated as strings.
          example: order-10482
        ping_id:
          type: string
          pattern: ^ping_[0-9a-z]{26}$
          description: >-
            The `id` returned by `POST /v1/ping`. Links this lead to the ping's
            match and pricing. A legacy ping UUID is rejected.
          example: ping_01jbx8k6y2m4n7p9q3r5s8t0vw
        bid_id:
          type: string
          pattern: ^(bid|prt|ping)_[0-9a-z]{26}$
          description: >-
            Any `bids[].id` returned by `POST /v1/ping` for your account. It is
            checked but doesn't change who gets the lead.
          example: bid_01h9z3c5e7g9j1k3m5n7p9r1st
        zip:
          type: string
          description: >-
            Postal code. Must be valid for your account's operating countries.
            With the source in test mode, zips `00001` to `00005` return fixed
            outcomes.
          example: '33139'
      additionalProperties:
        description: Additional fields as configured for your source and lead category.
    LeadResponseV1:
      title: Lead Response
      type: object
      required:
        - data
        - version
      properties:
        data:
          $ref: '#/components/schemas/LeadV1'
        version:
          type: string
          enum:
            - v1
          description: Always `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`.
    LeadV1:
      title: Lead
      type: object
      required:
        - id
        - status
        - price
      properties:
        id:
          type: string
          pattern: ^lead_[0-9a-z]{26}$
          description: The lead's public ID.
          example: lead_01jbx8m2d4f6g8h0j2k4m6n8pq
        status:
          type: string
          enum:
            - accepted
            - rejected
            - duplicate
          description: >-
            The outcome, decided by the source's status response mapping. By
            default, `accepted` covers leads that were assigned, posted to a
            partner, placed on the marketplace or parked in the Club; `rejected`
            covers Unassigned, Audit and Uncategorized leads; `duplicate` covers
            duplicates.
          example: accepted
        price:
          type: number
          description: >-
            What the source earns for the lead, in dollars. Always `0` unless
            `status` is `accepted`.
          example: 45
  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:
    UnauthenticatedV1:
      description: >-
        Credentials are missing or invalid. Every authentication failure returns
        the same error.
      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 credentials. Send a bearer token or Basic
                credentials for an active source.
            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.

````

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