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

# Qualify a lead (preview)

> **Preview endpoint. Read this before integrating.**

Unless `LEAD_QUALIFY_MODE=real` is configured server-side — it is not, in any
environment today — this endpoint returns **simulated** results. No credit
bureau is contacted, despite `plaid`, `experian`, `equifax` and
`transunion` appearing in the request and in `providers[].provider`. The
per-provider `request_id` values are generated locally, and the decision is
derived from the request body alone.

Check the response's `mode` field: `simulated` means no provider was
called. Do not present a `simulated` result to an end user as a verification
outcome.

Nothing is persisted — this endpoint writes no record and returns no id you can
look up later.

Requires the `write` scope.

**Preview endpoint. Read this before integrating.**

Unless `LEAD_QUALIFY_MODE=real` is configured server-side — it is not, in any
environment today — this endpoint returns **simulated** results. No credit
bureau is contacted, despite `plaid`, `experian`, `equifax` and
`transunion` appearing in the request and in `providers[].provider`. The
per-provider `request_id` values are generated locally, and the decision is
derived from the request body alone.

Check the response's `mode` field: `simulated` means no provider was
called. Do not present a `simulated` result to an end user as a verification
outcome.

Nothing is persisted — this endpoint writes no record and returns no id you can
look up later.

Requires the `write` scope.


## OpenAPI

````yaml openapi.json POST /v1/lead-qualifications
openapi: 3.1.0
info:
  contact:
    email: support@aura-app.ai
    name: Aura Support
  description: >-
    # Aura Partner Integrations API


    > **Alpha Release** - This API is under active development. Endpoints,
    request/response schemas, and behaviors may change without prior notice. We
    recommend pinning to specific response fields you need and handling unknown
    fields gracefully.


    Enterprise REST API for external partner integrations including

    commission platforms, external mobile apps, and client booking widgets.


    ## MCP Connector


    Aura also exposes a **Model Context Protocol** server at `/mcp` so AI

    assistants (Claude, ChatGPT) can answer questions about a user's own sales
    data.

    If you are building an assistant integration rather than a server-to-server
    one,

    that is almost certainly the surface you want — it is task-shaped ("prep me
    for

    my next call") rather than resource-shaped, and it handles auth per-user.


    Read-only. OAuth 2.1 + PKCE, with Clerk as the authorization server;
    discover it

    from `/.well-known/oauth-protected-resource`. Setup guide:

    https://docs.api.aura-app.ai/mcp-connector


    ## Authentication


    Authenticated endpoints support two authentication methods:


    **1. API Key (for partners and integrations):**

    ```

    Authorization: Bearer aura_pk_live_xxxxxxxxxxxxxxxx

    ```

    Get your API key from the Aura dashboard at Settings > API Keys.


    **2. Clerk JWT (for mobile and web apps):**

    ```

    Authorization: Bearer <clerk_jwt_token>

    ```

    Use Clerk's authentication SDK to obtain a JWT token with org claims.


    ## Rate Limiting


    - **Per API Key:** 100 requests/minute

    - **Per Organization:** 1000 requests/minute


    Rate limit headers are included in all responses:

    - `X-RateLimit-Limit`: Maximum requests allowed

    - `X-RateLimit-Remaining`: Remaining requests in current window

    - `X-RateLimit-Reset`: Unix timestamp when limit resets


    These counters are held per serving instance, so under concurrency the

    effective ceiling is higher than the number above and the headers describe
    one

    instance's view rather than a global total. Treat a 429 as backpressure to
    obey

    and pace your client to the documented rate — but do not rely on us to
    reject

    your 101st request, and do not derive a global remaining-quota figure from
    the

    headers. The limit may become globally enforced without notice, so a client

    that stays within it will not be affected when that happens.


    ## Pagination


    List endpoints support cursor-based pagination:

    - `limit`: Number of results per page (default: 50, max: 100)

    - `cursor`: Opaque cursor for next page


    ## Error Handling


    All errors follow a standard format:


    ```json

    {
      "success": false,
      "error": "Error message",
      "code": "ERROR_CODE"
    }

    ```


    Common HTTP status codes:

    - **400** Bad Request - Invalid input (`VALIDATION_ERROR`)

    - **401** Unauthorized - Missing or invalid API key (`AUTHENTICATION_ERROR`)

    - **402** Payment Required - The key is valid, but the organization's
    subscription is not active (`PAYMENT_REQUIRED`). Every authenticated
    endpoint can return this. Retrying will not help until the account's payment
    method is updated in Aura; surface it to the account owner rather than
    treating it as an auth failure.

    - **403** Forbidden - Insufficient permissions (`AUTHORIZATION_ERROR`)

    - **404** Not Found - Resource not found (`NOT_FOUND`)

    - **409** Conflict - Resource state prevents the operation (`CONFLICT`)

    - **413** Payload Too Large - Request body exceeds 256KB
    (`PAYLOAD_TOO_LARGE`)

    - **429** Too Many Requests - Rate limit exceeded (`RATE_LIMIT_EXCEEDED`)

    - **500** Internal Server Error - Server error (`INTERNAL_ERROR`)


    ## Webhooks


    Subscribe to real-time events using the Webhooks API. All webhook payloads

    are signed with HMAC-SHA256 for security verification.


    Delivery is at-least-once. Every payload carries an `idempotency_key` that

    is stable across retries of the same event, so you can enforce exactly-once

    with a `(subscription_id, idempotency_key)` unique constraint on your side.


    For full documentation, visit
    [docs.aura-app.ai/api](https://docs.aura-app.ai/api)
  license:
    name: Proprietary
  title: Aura Partner Integrations API
  version: 1.0.0-alpha
servers:
  - description: Production
    url: https://api.aura-app.ai
  - description: Staging
    url: https://staging-api.aura-app.ai
  - description: Local Development
    url: http://localhost:3001
security:
  - bearerAuth: []
tags:
  - description: Lead management operations
    name: Leads
  - description: Call booking and management
    name: Calls
  - description: Booking link configuration (read-only)
    name: Booking Links
  - description: Product catalog (read-only)
    name: Products
  - description: Payment tracking (read-only)
    name: Payments
  - description: Public booking creation
    name: Bookings
  - description: Real-time event subscriptions and webhook management
    name: Webhooks
  - description: >-
      Team member information for commission attribution. **Alpha** - schema may
      change without notice.
    name: Team (Alpha)
  - description: >-
      Dashboard analytics, lead source attribution, and objection analysis.
      **Alpha** - schema may change without notice.
    name: Analytics (Alpha)
  - description: System endpoints (health checks)
    name: System
paths:
  /v1/lead-qualifications:
    post:
      tags:
        - Lead Qualification
      summary: Qualify a lead (preview)
      description: >-
        **Preview endpoint. Read this before integrating.**


        Unless `LEAD_QUALIFY_MODE=real` is configured server-side — it is not,
        in any

        environment today — this endpoint returns **simulated** results. No
        credit

        bureau is contacted, despite `plaid`, `experian`, `equifax` and

        `transunion` appearing in the request and in `providers[].provider`. The

        per-provider `request_id` values are generated locally, and the decision
        is

        derived from the request body alone.


        Check the response's `mode` field: `simulated` means no provider was

        called. Do not present a `simulated` result to an end user as a
        verification

        outcome.


        Nothing is persisted — this endpoint writes no record and returns no id
        you can

        look up later.


        Requires the `write` scope.
      requestBody:
        content:
          application/json:
            schema:
              properties:
                answers:
                  additionalProperties:
                    maxLength: 500
                    type: string
                  default: {}
                  type: object
                consent_reference:
                  maxLength: 200
                  minLength: 1
                  type: string
                email:
                  format: email
                  type: string
                full_name:
                  maxLength: 200
                  minLength: 1
                  type: string
                lead_id:
                  type: string
                phone:
                  maxLength: 40
                  minLength: 7
                  type: string
                providers:
                  default:
                    - plaid
                    - experian
                    - equifax
                    - transunion
                  items:
                    enum:
                      - plaid
                      - experian
                      - equifax
                      - transunion
                    type: string
                  maxItems: 4
                  minItems: 1
                  type: array
              required:
                - full_name
                - email
                - consent_reference
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  consent_reference:
                    type: string
                  created_at:
                    type: string
                  email:
                    type: string
                  full_name:
                    type: string
                  id:
                    type: string
                  latency_ms:
                    minimum: 0
                    type: integer
                  lead_id:
                    nullable: true
                    type: string
                  mode:
                    description: >-
                      Whether the provider results in this response came from
                      real provider calls (`live`) or from the built-in
                      simulator (`simulated`). The provider names are actual
                      credit bureaus, so a `completed` result is otherwise
                      indistinguishable from one. Branch on this rather than
                      trusting `providers[].status`.
                    enum:
                      - live
                      - simulated
                    example: simulated
                    type: string
                  providers:
                    items:
                      properties:
                        error_category:
                          nullable: true
                          type: string
                        latency_ms:
                          minimum: 0
                          type: integer
                        provider:
                          type: string
                        request_id:
                          nullable: true
                          type: string
                        signals:
                          items:
                            type: string
                          type: array
                        status:
                          enum:
                            - completed
                            - pending
                            - unavailable
                            - not_configured
                            - failed
                          type: string
                      required:
                        - provider
                        - status
                        - latency_ms
                        - request_id
                        - signals
                        - error_category
                      type: object
                    type: array
                  qualification:
                    enum:
                      - qualified
                      - review
                      - unqualified
                      - unverifiable
                    type: string
                  reasons:
                    items:
                      type: string
                    type: array
                  route:
                    enum:
                      - book_call
                      - nurture
                      - manual_review
                      - unverifiable
                    type: string
                  score:
                    maximum: 100
                    minimum: 0
                    type: integer
                  status:
                    enum:
                      - completed
                      - partial
                      - failed
                    type: string
                  tier:
                    enum:
                      - A
                      - B
                      - C
                      - review
                    type: string
                required:
                  - mode
                  - id
                  - lead_id
                  - full_name
                  - email
                  - qualification
                  - score
                  - tier
                  - reasons
                  - route
                  - status
                  - providers
                  - latency_ms
                  - consent_reference
                  - created_at
                type: object
          description: Qualification result
        '400':
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  message:
                    type: string
                  requestId:
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - error
                  - message
                type: object
          description: Validation error
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiddlewareErrorResponse'
          description: Missing or invalid API key
          headers:
            X-Request-Id:
              description: Request identifier for support
              schema:
                type: string
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiddlewareErrorResponse'
          description: The organization's subscription is not active
          headers:
            X-Request-Id:
              description: Request identifier for support
              schema:
                type: string
        '403':
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                  error:
                    type: string
                  message:
                    type: string
                  requestId:
                    type: string
                  success:
                    enum:
                      - false
                    type: boolean
                required:
                  - success
                  - error
                  - message
                type: object
          description: Missing qualify scope
        '408':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiddlewareErrorResponse'
          description: >-
            The request exceeded its processing time limit. Check the outcome
            before retrying a write
          headers:
            X-Request-Id:
              description: Request identifier for support
              schema:
                type: string
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiddlewareErrorResponse'
          description: The request body exceeds 256KB
          headers:
            X-Request-Id:
              description: Request identifier for support
              schema:
                type: string
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiddlewareErrorResponse'
          description: Rate limit exceeded. Wait before retrying
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: string
            X-RateLimit-Limit:
              description: Requests allowed in the current window
              schema:
                type: string
            X-RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            X-RateLimit-Reset:
              description: Window reset as a Unix timestamp
              schema:
                type: string
            X-Request-Id:
              description: Request identifier for support
              schema:
                type: string
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiddlewareErrorResponse'
          description: >-
            Unexpected server failure. Include the request identifier when
            contacting support
          headers:
            X-Request-Id:
              description: Request identifier for support
              schema:
                type: string
      security:
        - bearerAuth: []
components:
  schemas:
    MiddlewareErrorResponse:
      properties:
        code:
          type: string
        error:
          type: string
        requestId:
          type: string
        success:
          enum:
            - false
          type: boolean
      required:
        - success
        - error
        - code
      type: object

````

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