> ## Documentation Index > Fetch the complete documentation index at: https://docs.3i.life/llms.txt > Use this file to discover all available pages before exploring further. # Ingest Live Lead or Scheduled Appointment > Delivers a live prospect or booked consultation appointment directly into the assigned 3i agent's CRM pipeline. - If appointment fields (`scheduled_at` or `appointment_date` + `appointment_time`) are provided, the lead's status is automatically set to `Scheduled` and placed on the agent's calendar agenda. - If an existing contact re-engages, the CRM automatically merges new information without creating duplicate records. ## OpenAPI ````yaml /openapi.yaml post /inbound-lead-gateway openapi: 3.0.3 info: title: 3i CRM Partner Inbound Lead & Appointment Gateway API description: >- High-throughput webhook ingestion gateway for delivering live leads and scheduled consultation appointments into the 3i CRM. version: 3.1.0 servers: - url: https://api.3i.life/functions/v1 description: Production Gateway Server security: [] tags: - name: Inbound Leads description: >- Endpoints for delivering live prospects and scheduled consultation appointments into 3i CRM. paths: /inbound-lead-gateway: post: tags: - Inbound Leads summary: Ingest Live Lead or Scheduled Appointment description: > Delivers a live prospect or booked consultation appointment directly into the assigned 3i agent's CRM pipeline. - If appointment fields (`scheduled_at` or `appointment_date` + `appointment_time`) are provided, the lead's status is automatically set to `Scheduled` and placed on the agent's calendar agenda. - If an existing contact re-engages, the CRM automatically merges new information without creating duplicate records. operationId: ingestLeadOrAppointment parameters: - name: Idempotency-Key in: header required: false description: >- Unique delivery identifier (e.g. UUID). Prevents duplicate lead records on network retries within 24 hours. schema: type: string example: vend_lead_9948201_retry_1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LeadSubmissionPayload' examples: Test (Sandbox): summary: 'Sandbox Test (listen: true)' description: >- Safe test request. Validates token, syntax, and field mapping without creating a live lead or dialing. value: listen: true first_name: Test last_name: Lead phone: '5125550100' email: test.lead@example.com state: TX city: Austin zipcode: '78704' coverage_type: Final Expense coverage_amount: '25000' custom_fields: lead_vendor: Partner Sandbox Test Live Lead: summary: Live Unscheduled Lead description: >- Delivers a live prospect directly into the agent's workable CRM dial queue. value: first_name: Marcus last_name: Vance phone: '5125550188' email: m.vance@example.com address: 1204 Pecan Grove Rd city: Austin state: TX zipcode: '78704' age: 63 coverage_type: Final Expense coverage_amount: '25000' monthly_budget: $85/mo smoker: false health_conditions: Controlled blood pressure; takes Lisinopril beneficiary: Eleanor Vance beneficiary_relationship: Spouse Booked Appt: summary: Live Booked Appointment description: >- Delivers a prospect and schedules a consultation directly on the agent's calendar agenda. value: first_name: Patricia last_name: Gomez phone: '3055550143' email: patricia.g@example.com address: 844 Ocean View Dr city: Miami state: FL zipcode: '33139' age: 58 coverage_type: Mortgage Protection coverage_amount: '150000' mortgage_type: Conventional 30yr mortgage_length_remaining: 24 years status: Scheduled schedule_type: appointment scheduled_at: '2026-09-30T18:00:00.000Z' scheduled_call: 09/30/2026 02:00 PM EDT appointment_timezone: America/New_York setter_dialer_name: Alexander Hayes notes: >- Appointment Confirmed: 09/25/2026 at 2:00 PM EDT. Setter Alexander verified spouse will be present. custom_fields: join_url: https://zoom.us/j/91827364510 cancel_url: https://calendly.com/cancellations/ABC123 reschedule_url: https://calendly.com/reschedulings/ABC123 responses: '200': description: Lead or appointment successfully ingested or resubmitted. content: application/json: schema: $ref: '#/components/schemas/IngestSuccessResponse' '400': description: Validation error or missing required contact name. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized. Missing or invalid source token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal processing or database constraint exception. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - SourceTokenAuth: [] components: schemas: LeadSubmissionPayload: type: object properties: name: type: string description: >- Full contact name. Alternatively, provide `first_name` and `last_name`. example: Marcus Vance first_name: type: string description: Contact first name. example: Marcus last_name: type: string description: Contact last name. example: Vance phone: type: string description: >- Primary phone number. Automatically normalized to 10-digit clean format. example: '5125550188' email: type: string format: email description: Primary email address. example: m.vance@example.com address: type: string description: Street address. example: 1204 Pecan Grove Rd city: type: string description: City name. example: Austin state: type: string description: >- 2-letter state code or full state name. Used to automatically detect timezone. example: TX zipcode: type: string description: 5-digit postal code. example: '78704' county: type: string description: County or parish name. example: Travis age: type: integer minimum: 18 maximum: 120 description: Age of the contact in years. example: 63 date_of_birth: type: string description: Date of birth (YYYY-MM-DD or MM/DD/YYYY). example: '1963-04-12' gender: type: string enum: - Male - Female description: Contact gender. Normalized automatically to Male or Female. example: Male status: type: string description: Set to `Scheduled` if the lead has an appointment booked. example: Scheduled scheduled_at: type: string format: date-time description: Canonical UTC ISO-8601 appointment timestamp. example: '2026-09-28T18:00:00.000Z' appointment_date: type: string description: Split appointment date if UTC ISO is not provided. example: '2026-09-28' appointment_time: type: string description: Split appointment local time. example: 02:00 PM appointment_timezone: type: string description: >- (Optional) IANA timezone. If omitted, automatically inferred from state or phone area code. example: America/New_York schedule_type: type: string enum: - appointment - follow_up default: appointment description: Type of schedule. example: appointment setter_dialer_name: type: string description: Name or ID of the human setter, dialer agent, or scheduling channel. example: Alexander Hayes (Setter Team Alpha) scheduled_call: type: string description: (Optional) Human-readable local date and time string. example: 09/28/2026 02:00 PM EDT tags: type: array items: type: string description: Array of tags to attach to the lead. example: - Scheduled - Setter Appointment - Mortgage Protection notes: type: string description: >- Appointment notes, qualifying verification details, and briefing text. example: >- APPOINTMENT CONFIRMED: 09/28/2026 at 2:00 PM EDT. Setter Alexander verified spouse will be present. coverage_type: type: string description: Requested insurance policy type. example: Mortgage Protection coverage_amount: type: string description: Requested coverage amount. example: '150000' current_coverage: type: string description: Existing insurance coverage details. example: None monthly_budget: type: string description: Target monthly budget. example: $120 annual_income: type: string description: Household yearly income. example: $48,000 occupation: type: string description: Job title or retirement status. example: Retired Postal Worker housing_type: type: string enum: - Own - Rent - Other description: Residence status. example: Own mortgage_type: type: string enum: - Conventional - FHA - VA - Fixed - ARM - USDA - Jumbo - Reverse description: Mortgage loan category. example: Conventional mortgage_length_remaining: type: string description: Remaining term on loan. example: 24 years monthly_payment: type: string description: Monthly mortgage payment. example: $1,450 smoker: type: boolean description: Tobacco usage flag. example: false health_conditions: type: string description: High-level health condition summary. example: Clean, non-smoker, no medications health_conditions_detail: type: string description: Specific prescriptions, hospitalizations, or surgery dates. example: Lisinopril 10mg daily. No hospitalizations. language: type: string description: Primary language preference. example: English branch_of_service: type: string description: Military branch (for veteran/military campaigns). example: Army military_status: type: string description: >- (Optional) Military service status (e.g. Disabled Veteran, Active Duty, Spouse / Family Member). For general veteran leads, lead_category and branch_of_service are sufficient. example: Disabled Veteran lead_category: type: string enum: - veterans - final-expense - mortgage-protection - nurses - truckers - iul - first-responder - federal-employee - senior - teacher - generic description: >- Primary campaign vertical/category. Common abbreviations and synonyms (e.g. fex, vets, military) are mapped automatically. example: veterans beneficiary: type: string description: Primary beneficiary name. example: Eleanor Vance beneficiary_relationship: type: string description: Relationship of beneficiary. example: Spouse beneficiary_count: type: string description: Number of designated beneficiaries. example: '1' dependents: type: string description: Number or details of dependent children. example: 2 children trusted_form_cert_url: type: string format: uri description: ActiveProspect TrustedForm certificate URL for TCPA verification. example: >- https://cert.trustedform.com/0123456789abcdef0123456789abcdef01234567 ip_address: type: string description: Client IP address at time of submission. example: 172.56.21.89 sms_consent: type: boolean description: Explicit consent flag for SMS messaging. example: true fbclid: type: string description: Facebook Click ID from ad URL. example: IwAR3_xV92K... fbc: type: string description: First-party Facebook click cookie from browser session. example: fb.1.1789918126987.IwAR3_xV92K fbp: type: string description: First-party Facebook browser tracking cookie. example: fb.1.1789676905645.579676956563071832 user_agent: type: string description: Client browser User-Agent string. example: Mozilla/5.0 (iPhone; CPU iPhone OS 26_6_2 like Mac OS X)... leadgen_id: type: string description: Meta Lead Ads native instant form submission ID. example: '491028401928401' ad_id: type: string description: Facebook Ad ID from campaign URL. example: '12020581920' utm_source: type: string description: Marketing traffic source. example: meta_ads utm_medium: type: string description: Marketing medium. example: paid_social utm_campaign: type: string description: Marketing campaign name. example: tx_veterans_fe_q3 utm_content: type: string description: Ad creative or variant. example: c-vets-video-1 utm_term: type: string description: Target keyword or audience. example: veterans life insurance listen: type: boolean description: >- Set to true to execute a pre-flight test without writing live leads to the CRM. default: false idempotency_key: type: string description: Alternative to sending the Idempotency-Key HTTP header. example: vend_lead_9948201_retry_1 custom_fields: type: object description: >- Partner-specific metadata, meeting links, or call recordings. Automatically captured in CRM. example: join_url: https://zoom.us/j/91827364510 setter_id: SETTER-442 call_recording_url: https://recordings.partner.com/rec_99214.mp3 IngestSuccessResponse: type: object required: - success - message properties: listen: type: boolean description: Returned and true when request was executed in Listen test mode. example: false success: type: boolean example: true message: type: string example: Lead created and appointment scheduled successfully lead_id: type: string format: uuid description: >- The CRM's primary UUID for the lead. Store this in your database to link records. example: b3040da5-9bd1-4a4b-8fd3-40e94bb5083f agent_id: type: string format: uuid description: UUID of the agent receiving the lead. example: 5170d1fa-fa77-4c7b-b5d1-93c6838a6a12 status: type: string example: Scheduled scheduled_at: type: string format: date-time description: Confirmed UTC ISO appointment timestamp. example: '2026-09-28T18:00:00.000Z' appointment_timezone: type: string description: Confirmed timezone. example: America/New_York schedule_type: type: string example: appointment resubmit: type: boolean description: Present and true when an existing lead was re-engaged and merged. example: false idempotent_replay: type: boolean description: >- Present and true when a cached delivery was safely replayed within 24 hours. example: false ErrorResponse: type: object required: - error - error_code properties: error: type: string description: Human-readable error description. example: Invalid or inactive token error_code: type: string enum: - MISSING_SOURCE_TOKEN - INVALID_SOURCE_TOKEN - UNAUTHORIZED - MISSING_AGENT_IDENTIFIER - INVALID_AGENT_IDENTIFIER - AGENT_NOT_FOUND - MISSING_NAME - INVALID_JSON - METHOD_NOT_ALLOWED - INSERT_FAILED - SERVER_ERROR - MISSING_SOURCE_ID - SOURCE_NOT_FOUND - LISTEN_INSERT_FAILED description: Machine-readable error code for programmatic retry logic. example: INVALID_SOURCE_TOKEN details: type: string description: Optional diagnostic details. example: >- The provided token could not be verified in the active source catalog. securitySchemes: SourceTokenAuth: type: apiKey in: header name: x-source-token description: Partner source token provided by 3i CRM client. ````