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

> Check pricing and match potential before submitting a full lead.

Vendor sources get a single `price`, never the bids behind it. Every other source gets the matching `bids`, each with the buyer's name for TCPA consent. Every ping that passes validation returns `200` whatever its `status`, so read `data.status` for the outcome, and keep `data.id` to send as `ping_id` when you [post the lead](https://docs.usejuiced.com/api-reference/endpoint/v1/leads.md).


## OpenAPI

````yaml POST /v1/ping
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/ping:
    post:
      tags:
        - v1
      summary: Submit a ping
      description: >-
        Submits partial lead data to check for matching bids before sending the
        full lead. Use it to see pricing and availability before you commit to a
        full lead submission.


        The response depends on your source type.

        - **Vendor sources** receive a single `price`, never the bids behind it.

        - **Every other source** receives the matching `bids`, each with the
        buyer's name for TCPA consent.


        Every ping that passes validation returns `200`, whatever its `status`.
        Keep the returned `id` and send it as `ping_id` when you post the lead.
      operationId: createPingV1
      parameters:
        - $ref: '#/components/parameters/PartnerIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PingRequest'
            examples:
              Minimal ping (zip only):
                summary: Minimal ping (zip only)
                value:
                  zip: '90210'
              Ping with more fields:
                summary: Ping with more fields
                value:
                  zip: '33139'
                  state: FL
                  urgency: high
      responses:
        '200':
          description: Ping evaluated. Check `data.status` for the outcome.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponseV1'
              examples:
                Matched with bids:
                  summary: Matched with bids
                  value:
                    data:
                      id: ping_01jbx8k6y2m4n7p9q3r5s8t0vw
                      status: matched
                      bids:
                        - id: bid_01h9z3c5e7g9j1k3m5n7p9r1st
                          price: 45
                          tcpa_name: Nectarflix Entertainment
                          customer_id: cus_01h8y2b4d6f8h0j2k4m6p8r0tv
                        - id: prt_01h7x1a3c5e7g9j1k3m5n7q9sv
                          price: 38.5
                          tcpa_name: The Mangolorian Security
                          partner_id: prt_01h7x1a3c5e7g9j1k3m5n7q9sv
                    version: v1
                Matched (vendor source):
                  summary: Matched (vendor source)
                  value:
                    data:
                      id: ping_01jbx8k6y2m4n7p9q3r5s8t0vw
                      status: matched
                      price: 45
                    version: v1
                Matched with no bidder (marketplace or Club):
                  summary: Matched with no bidder (marketplace or Club)
                  value:
                    data:
                      id: ping_01jbx8k6y2m4n7p9q3r5s8t0vw
                      status: matched
                      bids:
                        - id: ping_01jbx8k6y2m4n7p9q3r5s8t0vw
                          price: 75
                          tcpa_name: Juiceversal Pictures
                    version: v1
                No match:
                  summary: No match
                  value:
                    data:
                      id: ping_01jbx8k6y2m4n7p9q3r5s8t0vw
                      status: no_match
                      bids: []
                    version: v1
                Duplicate:
                  summary: Duplicate
                  value:
                    data:
                      id: ping_01jbx8k6y2m4n7p9q3r5s8t0vw
                      status: duplicate
                      bids: []
                    version: v1
                Rejected by the loop guard:
                  summary: Rejected by the loop guard
                  value:
                    data:
                      id: ping_01jbx8k6y2m4n7p9q3r5s8t0vw
                      status: rejected
                      bids: []
                      reason: cycle_detected
                    version: v1
        '401':
          $ref: '#/components/responses/UnauthenticatedV1'
        '422':
          description: The ping failed validation.
          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 zip field is required.
                      errors:
                        zip:
                          - The zip field is required.
                    version: v1
        '429':
          $ref: '#/components/responses/RateLimitedV1'
        '500':
          $ref: '#/components/responses/ServerErrorV1'
components:
  parameters:
    PartnerIdHeader:
      name: X-Partner-Id
      in: header
      required: false
      description: >-
        Public ID of the partner you're pinging on behalf of. The ping is
        recorded against that partner when the partner is linked to the source
        whose credentials you use. Optional but recommended for any
        partner-mediated integration.
      schema:
        type: string
        example: prt_01h7x1a3c5e7g9j1k3m5n7q9sv
  schemas:
    PingRequest:
      title: Ping Request
      type: object
      required:
        - zip
      properties:
        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: '90210'
      additionalProperties:
        description: >-
          Additional fields as configured for your source and lead category.
          Only fields marked required for ping must be sent.
    PingResponseV1:
      title: Ping Response
      type: object
      required:
        - data
        - version
      properties:
        data:
          $ref: '#/components/schemas/PingV1'
        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`.
    PingV1:
      title: Ping
      type: object
      required:
        - id
        - status
      properties:
        id:
          type: string
          pattern: ^ping_[0-9a-z]{26}$
          description: The ping's ID. Send it as `ping_id` when you post the lead.
          example: ping_01jbx8k6y2m4n7p9q3r5s8t0vw
        status:
          type: string
          enum:
            - matched
            - no_match
            - duplicate
            - rejected
          description: >-
            How the ping was answered. `matched` means a buyer (or the
            marketplace or Club) will take the lead. `no_match` means nobody
            will, including when the source has reached a lead quota.
            `duplicate` means it matched a duplicate check. `rejected` means it
            was refused before matching.
          example: matched
        price:
          type: number
          description: >-
            Vendor sources only. The price offered for the lead, in dollars. `0`
            when there's no match.
          example: 45
        bids:
          type: array
          description: >-
            Every source except vendors. The bids behind the answer. Empty when
            there's no match.
          items:
            $ref: '#/components/schemas/BidV1'
        reason:
          type: string
          enum:
            - cycle_detected
            - max_hops_exceeded
          description: >-
            Only on a ping rejected by the distribution loop guard, because the
            ping already passed through this account or exceeded the hop limit.
    BidV1:
      title: Bid
      type: object
      required:
        - id
        - price
        - tcpa_name
      properties:
        id:
          type: string
          description: >-
            The bid's ID. It's a `bid_…` for a customer bid, the partner's
            `prt_…` for a partner, or the ping's own `ping_…` when the match has
            no bidder behind it (marketplace or Club). Echo it as `bid_id` when
            you post the lead.
          example: bid_01h9z3c5e7g9j1k3m5n7p9r1st
        price:
          type: number
          description: Price offered for the lead, in dollars.
          example: 45
        tcpa_name:
          type:
            - string
            - 'null'
          description: Buyer name to use in TCPA consent language.
          example: Juiceversal Pictures
        customer_id:
          type: string
          description: Present when a customer placed the bid. The customer's public ID.
          example: cus_01h8y2b4d6f8h0j2k4m6p8r0tv
        partner_id:
          type: string
          description: Present when a partner made the offer. The partner's public ID.
          example: prt_01h7x1a3c5e7g9j1k3m5n7q9sv
  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.