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

# Update Lead Status

> Notifies Leadhub of a status change for a lead (e.g. registration completed, loan issued).

Called by the advertiser when a relevant event occurs during lead processing. Leadhub will forward the notification to the publisher's configured callback URL.

The `lead_id` is provided by Leadhub in the `POST /lead` response and must be included in the URL path.




## OpenAPI

````yaml POST /lead/{lead_id}/status
openapi: 3.1.0
info:
  title: Leadhub API
  version: 2.0.0
  description: >
    Leadhub connects publishers (affiliates) with financial advertisers.
    Publishers submit customer leads and receive a simple accept/reject response
    with a redirect URL when the lead is accepted.


    ## Authentication


    All requests must include your API Key in the `apikey` header. Contact
    Leadhub to obtain your `publisher_id` and API Key.


    ## Publisher integration flow


    1. Publisher submits a lead via `POST /lead` with customer data

    2. Leadhub validates data, checks eligibility and distributes to matching
    advertisers

    3. Response indicates whether the lead was **new**, **distributed** or
    **rejected**

    4. If distributed, redirect the customer to the `redirect_url` to continue
    the process

    5. When the customer converts, Leadhub sends a notification to the
    publisher's configured callback URL


    ## Advertiser notifications


    When a lead converts, Leadhub notifies the publisher via a GET request to
    the publisher's callback URL:


    ```

    GET {publisher_callback_url}?lead_id={lead_id}&event={event}

    ```


    Configure your callback URL with your account manager.
servers:
  - url: https://{tenant}.techea.eu/api/v1
    description: Production
  - url: https://sandbox.techea.eu/api/v1
    description: Sandbox
security:
  - ApiKeyAuth: []
tags:
  - name: publisher
    description: Endpoints for publishers (affiliates)
  - name: advertiser
    description: Endpoints for advertisers (lenders)
paths:
  /lead/{lead_id}/status:
    post:
      tags:
        - advertiser
      summary: Update lead status
      description: >
        Notifies Leadhub of a status change for a lead (e.g. registration
        completed, loan issued).


        Called by the advertiser when a relevant event occurs during lead
        processing. Leadhub will forward the notification to the publisher's
        configured callback URL.


        The `lead_id` is provided by Leadhub in the `POST /lead` response and
        must be included in the URL path.
      operationId: updateLeadStatus
      parameters:
        - name: lead_id
          in: path
          required: true
          description: Lead ID provided by Leadhub at submission time
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadStatusUpdate'
            example:
              status: converted
              advertiser_id: 5490c3cc-0d44-4b50-8888-8dd43736052a
              metadata:
                amount: 8000
                term_months: 24
      responses:
        '200':
          description: Status update received and processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadStatusUpdateResponse'
        '400':
          description: Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Advertiser API Key missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Lead not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    LeadStatusUpdate:
      type: object
      required:
        - status
      properties:
        status:
          $ref: '#/components/schemas/AdvertiserLeadStatus'
        advertiser_id:
          type: string
          description: Advertiser's reference for this lead
        metadata:
          type: object
          description: Additional data related to the status update
          additionalProperties: true
    LeadStatusUpdateResponse:
      type: object
      properties:
        lead_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/AdvertiserLeadStatus'
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable description
        details:
          type: array
          description: Field-level validation errors. Only present in `400` responses.
          items:
            type: object
            properties:
              field:
                type: string
              issue:
                type: string
      example:
        error: validation_error
        message: Request body validation failed
        details:
          - field: product_data.loan_amount
            issue: must be between 500 and 75000
    AdvertiserLeadStatus:
      type: string
      description: Status reported by the advertiser.
      enum:
        - converted
        - rejected
      x-enumDescriptions:
        converted: Customer accepted and product issued
        rejected: Customer rejected after your evaluation
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: API Key provided by TECHEA

````