> ## 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. ## OpenAPI ````yaml POST /leads openapi: 3.1.0 info: title: Juiced API description: API for submitting and managing leads in Juiced. version: 1.0.0 servers: - url: https://usejuiced.com/api description: Production server security: - Basic Auth: [] - Bearer Token: [] tags: - name: Ping description: Check for matching bids before submitting a full lead. - name: Leads description: Submit complete leads for processing and assignment. paths: /leads: post: tags: - Leads summary: Submit a lead description: >- Submits a complete lead for processing and assignment. The lead will be validated, checked for duplicates, matched to a lead type, and assigned to a customer (or placed in the marketplace). If you previously submitted a ping, include the `ping_id` and optionally a `bid_id` to reference that ping's pricing. operationId: createLead parameters: - $ref: '#/components/parameters/PartnerIdHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LeadRequest' examples: basic: summary: Basic lead submission value: 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' withPingId: summary: Lead with ping reference value: ping_id: f47ac10b-58cc-4372-a567-0e02b2c3d479 bid_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7 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' complete: summary: Complete lead with all fields value: first_name: John last_name: Lemon email: john.lemon@zestforsuccess.com phone: 555-246-8135 address_1: 55 Squeeze Street address_2: Suite 12 city: Pulp City state: FL zip: '33101' county: Miami-Dade testLead: summary: Test lead submission value: is_test: true first_name: Test last_name: User email: test@example.com phone: 555-000-0000 address_1: 123 Test Street city: Test City state: FL zip: '00002' responses: '201': description: Lead created successfully content: application/json: schema: $ref: '#/components/schemas/LeadResponse' examples: assigned: summary: Lead assigned to customer value: lead_uuid: f47ac10b-58cc-4372-a567-0e02b2c3d479 lead_public_id: lead_01arz3ndektsv4rrffq69g5fav status: assigned price: 45 duplicate: summary: Lead is a duplicate value: lead_uuid: f47ac10b-58cc-4372-a567-0e02b2c3d479 lead_public_id: lead_01arz3ndektsv4rrffq69g5fav status: duplicate price: 0 unassigned: summary: Lead unassigned (no matching buyers) value: lead_uuid: f47ac10b-58cc-4372-a567-0e02b2c3d479 lead_public_id: lead_01arz3ndektsv4rrffq69g5fav status: unassigned price: 0 marketplace: summary: Lead placed in marketplace value: lead_uuid: f47ac10b-58cc-4372-a567-0e02b2c3d479 lead_public_id: lead_01arz3ndektsv4rrffq69g5fav status: marketplace price: 0 pending: summary: Lead pending assignment value: lead_uuid: f47ac10b-58cc-4372-a567-0e02b2c3d479 lead_public_id: lead_01arz3ndektsv4rrffq69g5fav status: pending price: 0 audit: summary: Test lead moved to audit value: lead_uuid: f47ac10b-58cc-4372-a567-0e02b2c3d479 status: audit price: 0 '401': $ref: '#/components/responses/Unauthorized' '422': description: Validation error or ping reference error content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/PingReferenceError' examples: validationError: summary: Validation error value: message: The given data was invalid. errors: email: - The email field must be a valid email address. zip: - >- The postal code is not valid for this account's operating countries. pingNotFound: summary: Ping not found value: error: Ping could not be found with the provided ping ID pingExpired: summary: Ping expired value: error: Ping ID has expired dataMismatch: summary: Data mismatch value: error: Lead data does not match ping data components: parameters: PartnerIdHeader: name: X-Partner-Id in: header required: false description: >- Public ID of the partner the submission is attributed to. Optional but recommended for any partner-mediated integration. schema: type: string example: partner_01arz3ndektsv4rrffq69g5fav schemas: LeadRequest: title: Lead Request type: object required: - zip properties: ping_id: type: string format: uuid description: >- Reference to a previous ping request. Include to link this lead to prior pricing. example: f47ac10b-58cc-4372-a567-0e02b2c3d479 bid_id: type: string format: uuid description: >- Specific bid to accept from the ping response. Only applicable for internal sources. example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 zip: type: string description: Postal code. Must be valid for your account's operating countries. example: '33139' is_test: type: boolean description: >- Mark this lead as test data. Test leads are automatically moved to Audit status and won't be distributed. Only works when test mode is enabled on the source. default: false example: true additionalProperties: description: Additional fields as configured for your source and lead type. LeadResponse: title: Lead Response type: object properties: lead_uuid: type: string format: uuid description: >- Internal UUID for the lead. Prefer `lead_public_id` for external references. deprecated: true example: f47ac10b-58cc-4372-a567-0e02b2c3d479 lead_public_id: type: string description: >- Public identifier for the lead. Use this for display, URLs, and external references. example: lead_01arz3ndektsv4rrffq69g5fav minLength: 31 maxLength: 31 pattern: ^lead_[0-9a-z]{26}$ status: type: string enum: - pending - assigned - duplicate - unassigned - marketplace - audit description: Current status of the lead. example: assigned price: type: number format: float description: Price paid for the lead. Zero if not yet assigned. example: 45 ValidationError: title: Validation Error type: object properties: message: type: string example: The given data was invalid. errors: type: object additionalProperties: type: array items: type: string example: email: - The email field must be a valid email address. PingReferenceError: title: Ping Reference Error type: object properties: error: type: string enum: - Ping could not be found with the provided ping ID - Ping ID has expired - Lead data does not match ping data UnauthorizedError: title: Unauthorized Error type: object properties: message: type: string example: Unauthorized responses: Unauthorized: description: Authentication credentials are missing or invalid. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' 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. ````