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

# Create lead

> 
Create a new lead in your organization.

**Use Cases:**
- Partner systems creating leads from external sources
- CRM integrations syncing leads into Aura
- Manual lead entry from external applications

**Required fields:**
- `email` - Must be a valid email address

**Optional fields:**
- `full_name`, `phone`, `company`, `timezone`, `visitor_id`, `metadata`

New leads are created with status "new" by default.
  

Create a new lead in your organization.

**Use Cases:**

* Partner systems creating leads from external sources
* CRM integrations syncing leads into Aura
* Manual lead entry from external applications

**Required fields:**

* `email` - Must be a valid email address

**Optional fields:**

* `full_name`, `phone`, `company`, `timezone`, `visitor_id`, `metadata`

New leads are created with status "new" by default.


## OpenAPI

````yaml openapi.json POST /v1/leads
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/leads:
    post:
      tags:
        - Leads
      summary: Create lead
      description: |-

        Create a new lead in your organization.

        **Use Cases:**
        - Partner systems creating leads from external sources
        - CRM integrations syncing leads into Aura
        - Manual lead entry from external applications

        **Required fields:**
        - `email` - Must be a valid email address

        **Optional fields:**
        - `full_name`, `phone`, `company`, `timezone`, `visitor_id`, `metadata`

        New leads are created with status "new" by default.
          
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLeadBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadSuccessResponse'
          description: Successfully created lead
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error (e.g., duplicate email)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid or missing API key
        '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:
                $ref: '#/components/schemas/MiddlewareErrorResponse'
          description: The API key does not have the required scope
          headers:
            X-Request-Id:
              description: Request identifier for support
              schema:
                type: string
        '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:
    CreateLeadBody:
      properties:
        company:
          description: Company name
          example: Acme Corp
          type: string
        email:
          description: Email address (required)
          example: john@example.com
          format: email
          type: string
        full_name:
          description: Full name of the lead
          example: John Doe
          type: string
        metadata:
          additionalProperties:
            nullable: true
          description: >-
            Lead attribution metadata. See the LeadMetadata schema for
            documented camelCase keys (utmSource, fbclid, etc.). Unknown keys
            are accepted for forward compatibility but only the documented
            fields are part of the stable contract. Pass null or omit to skip.
          nullable: true
          properties:
            city:
              description: City name from IP geolocation.
              nullable: true
              type: string
            country:
              description: Country name from IP geolocation.
              nullable: true
              type: string
            countryCode:
              description: ISO 3166-1 alpha-2 country code from IP geolocation.
              example: US
              nullable: true
              type: string
            dataConsentAcceptedAt:
              description: >-
                ISO 8601 timestamp when GDPR data consent was accepted.
                Generated server-side at consent capture.
              example: '2026-05-08T14:23:11.000Z'
              nullable: true
              type: string
            dclid:
              description: Google Display Network click ID.
              nullable: true
              type: string
            epik:
              description: Pinterest click ID.
              nullable: true
              type: string
            fbclid:
              description: >-
                Meta (Facebook + Instagram) click ID. Pixel computes _fbc cookie
                from this.
              nullable: true
              type: string
            gadSource:
              description: Google Ads source attribute (e.g. 'AdWords').
              nullable: true
              type: string
            gbraid:
              description: Google Ads iOS-era click ID.
              nullable: true
              type: string
            gclid:
              description: Google Ads classic click ID.
              nullable: true
              type: string
            gclsrc:
              description: Google Ads source identifier.
              nullable: true
              type: string
            hyclid:
              description: Hyros click ID. Aura's primary attribution platform.
              nullable: true
              type: string
            ipAddress:
              description: Client IP address. Used for geolocation enrichment.
              nullable: true
              type: string
            landingPage:
              description: >-
                Originating landing-page URL (host + pathname, query string
                excluded). Forwarded by the Aura embed script from the host
                page's own location, so two landing pages sharing one booking
                link and identical UTMs stay distinguishable. Unlike `referrer`,
                this preserves the page path. Absent for direct (non-embedded)
                bookings.
              example: acme.com/sales-manager
              nullable: true
              type: string
            landingUrl:
              description: >-
                The full address of the host page, query string included.
                Recorded by the Aura embed loaders with credentials removed.
                Like the UTM fields it is visitor-supplied attribution, not a
                verified address; a value supplied through this API is stored as
                sent. Surfaced on the lead as `source.landing_url`. Absent for
                direct (non-embedded) bookings.
              example: https://acme.com/sales-manager?utm_source=google&variant=b
              nullable: true
              type: string
            language:
              description: Browser language preference (e.g. 'en-US').
              example: en-US
              nullable: true
              type: string
            latitude:
              description: Latitude from IP geolocation.
              nullable: true
              type: number
            liFatId:
              description: LinkedIn Ads first-party ad tracking ID.
              nullable: true
              type: string
            longitude:
              description: Longitude from IP geolocation.
              nullable: true
              type: number
            msclkid:
              description: Microsoft Ads (Bing) click ID.
              nullable: true
              type: string
            partner:
              description: Partner program name or ID.
              nullable: true
              type: string
            rdtCid:
              description: Reddit click ID.
              nullable: true
              type: string
            ref:
              description: Generic referral code or partner attribution identifier.
              nullable: true
              type: string
            referrer:
              description: >-
                HTTP referrer URL. For embeds, the host page where the booking
                widget was displayed (e.g. 'acme.com/book-a-call'). For direct
                visits, the traffic source URL.
              example: https://acme.com/book-a-call
              nullable: true
              type: string
            region:
              description: Region/state from IP geolocation.
              nullable: true
              type: string
            scCid:
              description: Snapchat click ID.
              nullable: true
              type: string
            screenHeight:
              description: Screen height in pixels.
              nullable: true
              type: number
            screenWidth:
              description: Screen width in pixels.
              nullable: true
              type: number
            setterCode:
              description: >-
                The first setter link code saved for this lead
                (`?aura_setter=`). It may come from a later visit than the
                lead's first, and it does not record who set any call. Use a
                call's `setter_id` for that.
              nullable: true
              type: string
            ttclid:
              description: TikTok Ads click ID.
              nullable: true
              type: string
            twclid:
              description: X (Twitter) Ads click ID.
              nullable: true
              type: string
            userAgent:
              description: Browser user agent string. Used for device/browser analytics.
              nullable: true
              type: string
            utmCampaign:
              description: >-
                UTM campaign param (e.g. 'summer_promo'). Identifies the
                specific campaign.
              example: spring-2026
              nullable: true
              type: string
            utmContent:
              description: >-
                UTM content param. Differentiates ad creatives or A/B test
                variants.
              nullable: true
              type: string
            utmId:
              description: GA4 utm_id parameter for cross-platform attribution.
              nullable: true
              type: string
            utmMedium:
              description: >-
                UTM medium param (e.g. 'cpc', 'email', 'social'). Identifies the
                marketing channel type.
              example: cpc
              nullable: true
              type: string
            utmSource:
              description: >-
                UTM source param (e.g. 'google', 'facebook'). Identifies the
                traffic platform that drove the lead.
              example: google
              nullable: true
              type: string
            utmTerm:
              description: UTM term param. Paid search keywords or targeting criteria.
              nullable: true
              type: string
            wbraid:
              description: Google Ads web-to-app click ID.
              nullable: true
              type: string
            yclid:
              description: Yandex click ID.
              nullable: true
              type: string
          type: object
        phone:
          description: >-
            Phone number in E.164 format (validated): `+` followed by country
            code and digits, no spaces or hyphens.
          example: '+14155552671'
          pattern: ^\+[1-9]\d{1,14}$
          type: string
        timezone:
          description: >-
            Lead's timezone. Must be an IANA zone (e.g. Europe/Berlin); the
            common aliases EST, CET, PST8PDT and US/Pacific are accepted, and
            surrounding whitespace is trimmed. Anything else is DISCARDED rather
            than rejected: the request still succeeds and every other field is
            applied. On create the timezone is left empty; on update the lead's
            existing timezone is left UNCHANGED, never cleared. If an unusable
            timezone is the only field supplied to an update, the request is
            rejected, because nothing would have been applied. Rejecting
            outright at the boundary is planned once telemetry shows nobody
            depends on the current leniency (AUR-2090).
          example: America/New_York
          type: string
        visitor_id:
          description: >-
            Anonymous first-party visitor identifier used to attach the pre-lead
            funnel journey.
          example: voics_550e8400-e29b-41d4-a716-446655440000
          maxLength: 128
          minLength: 8
          type: string
      required:
        - email
      type: object
    LeadSuccessResponse:
      properties:
        data:
          $ref: '#/components/schemas/Lead'
        success:
          enum:
            - true
          type: boolean
      required:
        - success
        - data
      type: object
    ErrorResponse:
      properties:
        code:
          description: Error code for programmatic handling
          example: NOT_FOUND
          type: string
        error:
          description: Human-readable error message
          example: Lead not found
          type: string
        requestId:
          description: Request ID for support debugging
          example: req_abc123
          type: string
        success:
          enum:
            - false
          type: boolean
      required:
        - success
        - error
        - code
      type: object
    MiddlewareErrorResponse:
      properties:
        code:
          type: string
        error:
          type: string
        requestId:
          type: string
        success:
          enum:
            - false
          type: boolean
      required:
        - success
        - error
        - code
      type: object
    Lead:
      properties:
        attribution:
          $ref: '#/components/schemas/PublicAttribution'
        company:
          description: Company name
          example: Acme Corp
          nullable: true
          type: string
        consent:
          description: >-
            Every consent box and what the person chose, in the order they were
            recorded. This includes Aura's own box for appointment texts, and
            STOP replies. `agreed` is true only while they agree for the lead's
            current phone number. An empty list means no consent is on file:
            that is not the same as `declined`, but treat it as no consent. A
            box they did not tick is only recorded once they finish the form.
            Consent can change after you read it, for example when the person
            replies STOP, so read the lead again right before you text them. The
            phone number is sent either way.
          example:
            - agreed: true
              at: '2026-10-08T10:00:00.000Z'
              disclosure: null
              granted_at: null
              id: 6f1b2c3d-0000-4000-8000-000000000001
              kind: custom
              label: >-
                I agree to receive appointment reminder texts from Acme Inc. Msg
                & data rates may apply. Reply STOP to opt out.
              links:
                - text: SMS Terms
                  url: https://example.com/sms-terms
                - text: Privacy Policy
                  url: https://example.com/privacy
              phone: '+15551234567'
              source: booking_form
              state: granted
            - agreed: false
              at: '2026-10-08T10:00:00.000Z'
              disclosure: null
              granted_at: null
              id: 6f1b2c3d-0000-4000-8000-000000000002
              kind: custom
              label: I agree to receive promotional texts from Acme Inc.
              links: []
              phone: '+15551234567'
              source: booking_form
              state: declined
          items:
            $ref: '#/components/schemas/LeadConsent'
          type: array
        created_at:
          description: ISO 8601 timestamp when lead was created
          example: '2026-01-17T08:00:00Z'
          format: date-time
          type: string
        disqualification_data:
          $ref: '#/components/schemas/DisqualificationData'
        email:
          description: Email address
          example: john@example.com
          nullable: true
          type: string
        full_name:
          description: Full name of the lead
          example: John Doe
          nullable: true
          type: string
        id:
          description: Unique identifier for the lead
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
        last_payment_at:
          description: Last payment timestamp
          nullable: true
          type: string
        metadata:
          $ref: '#/components/schemas/LeadMetadata'
        notes:
          $ref: '#/components/schemas/LeadNotes'
        payment_count:
          description: Number of payments received
          nullable: true
          type: number
        payment_status:
          description: >-
            Rolled-up payment state for this lead: `partial` once any payment
            has been recorded, `pending` before the first one or after refunds
            return the total to zero. It does not report whether a deal is paid
            in full, so do not treat `partial` as a shortfall — use
            total_paid_cents for the amount.
          nullable: true
          type: string
        phone:
          description: Phone number in E.164 format
          example: '+14155552671'
          nullable: true
          type: string
        pipeline_stage:
          description: >-
            The column the lead is in on the Opportunities board right now,
            worked out from its calls each time you read it. Use this to show
            where a lead stands. `status` is a stored value that can lag behind:
            when a guest confirms a call, `pipeline_stage` says `confirmed` at
            once, while `status` can still say `booked` until Aura's status sync
            updates it. The same value as `stage` on the lead's opportunities.
            For up to an hour after a disqualification rule changes, it can
            differ from the board, which applies the new rule on its next sync.
            Null only if Aura could not read the lead's calls.
          enum:
            - interested
            - disqualified
            - qualified
            - booked
            - confirmed
            - declined
            - cancelled
            - attended
            - unfit
            - no_show
            - follow_up
            - lost
            - won
            - null
          example: confirmed
          nullable: true
          type: string
        source:
          description: >-
            Lead source attribution. Use with booking_link_id on calls to get
            the full picture: which campaign drove this lead, from which page,
            into which funnel.
          nullable: true
          properties:
            attribution_platform:
              description: >-
                Derived ad platform (meta, google, tiktok, linkedin, …) from
                click IDs or utm_source
              example: google
              nullable: true
              type: string
            city:
              description: City detected from the visitor's IP address
              example: San Francisco
              nullable: true
              type: string
            country:
              description: Country detected from the visitor's IP address
              example: US
              nullable: true
              type: string
            country_code:
              description: ISO 3166-1 alpha-2 country code
              example: US
              nullable: true
              type: string
            epik:
              description: Pinterest Ads click ID
              nullable: true
              type: string
            fbc:
              description: Meta _fbc cookie (framed click ID)
              nullable: true
              type: string
            fbclid:
              description: Meta (Facebook/Instagram) click ID
              nullable: true
              type: string
            fbp:
              description: Meta _fbp cookie (browser ID)
              nullable: true
              type: string
            gbraid:
              description: Google Ads iOS app-to-web click ID
              nullable: true
              type: string
            gclid:
              description: Google Ads click ID
              nullable: true
              type: string
            hyclid:
              description: Hyros click ID
              nullable: true
              type: string
            landing_page:
              description: >-
                Originating landing-page URL (host + pathname). Preserves the
                page path that `referrer` loses cross-origin, so pages sharing
                one booking link and identical UTMs stay distinguishable.
              example: acme.com/sales-manager
              nullable: true
              type: string
            landing_url:
              description: >-
                The full address of the page the lead landed on, query string
                included. Recorded by the Aura embed loaders with credentials
                removed. Like the UTM fields it is visitor-supplied attribution,
                not a verified address; a value supplied through this API as
                `metadata.landingUrl` is stored as sent. Null when the lead has
                none. Optional: a client must not require it.
              example: https://acme.com/sales-manager?utm_source=google&variant=b
              nullable: true
              type: string
            li_fat_id:
              description: LinkedIn Ads click ID
              nullable: true
              type: string
            msclkid:
              description: Microsoft/Bing Ads click ID
              nullable: true
              type: string
            rdt_cid:
              description: Reddit Ads click ID
              nullable: true
              type: string
            referrer:
              description: >-
                HTTP referrer URL. For embeds, this is the host page where the
                booking widget was displayed. For direct visits, this is the
                traffic source URL.
              example: https://acme.com/book-a-call
              nullable: true
              type: string
            region:
              description: State/region detected from the visitor's IP address
              example: CA
              nullable: true
              type: string
            sc_cid:
              description: Snapchat Ads click ID
              nullable: true
              type: string
            ttclid:
              description: TikTok Ads click ID
              nullable: true
              type: string
            twclid:
              description: X (Twitter) Ads click ID
              nullable: true
              type: string
            utm_campaign:
              description: >-
                UTM campaign parameter — identifies the specific marketing
                campaign
              example: summer_promo
              nullable: true
              type: string
            utm_content:
              description: >-
                UTM content parameter — differentiates ad creatives or A/B test
                variants
              nullable: true
              type: string
            utm_id:
              description: GA4 campaign ID (utm_id)
              example: '1234567890'
              nullable: true
              type: string
            utm_medium:
              description: >-
                UTM medium parameter — identifies the marketing channel type
                (e.g., cpc, email, social)
              example: cpc
              nullable: true
              type: string
            utm_source:
              description: >-
                UTM source parameter — identifies the traffic platform (e.g.,
                google, facebook, twitter)
              example: google
              nullable: true
              type: string
            utm_term:
              description: UTM term parameter — paid search keywords or targeting criteria
              nullable: true
              type: string
            wbraid:
              description: Google Ads web-to-iOS click ID
              nullable: true
              type: string
          required:
            - utm_source
            - utm_medium
            - utm_campaign
            - utm_term
            - utm_content
            - referrer
            - landing_page
            - utm_id
            - city
            - region
            - country
            - country_code
            - fbclid
            - gclid
            - fbc
            - fbp
            - gbraid
            - wbraid
            - msclkid
            - li_fat_id
            - ttclid
            - twclid
            - hyclid
            - epik
            - sc_cid
            - rdt_cid
            - attribution_platform
          type: object
        status:
          description: Lead status
          example: new
          type: string
        timezone:
          description: Lead's timezone
          example: America/New_York
          nullable: true
          type: string
        total_paid_cents:
          description: Total amount paid in cents
          nullable: true
          type: number
        updated_at:
          description: ISO 8601 timestamp when lead was last updated
          example: '2026-01-17T09:30:00Z'
          format: date-time
          type: string
      required:
        - id
        - full_name
        - email
        - phone
        - company
        - status
        - pipeline_stage
        - notes
        - metadata
        - source
        - attribution
        - timezone
        - disqualification_data
        - payment_status
        - payment_count
        - total_paid_cents
        - last_payment_at
        - consent
        - created_at
        - updated_at
      type: object
    PublicAttribution:
      additionalProperties:
        maxLength: 500
        minLength: 1
        type: string
      description: >-
        Flat map of every attribution parameter the record carried, returned
        under its own name. Known and provider-specific keys share one object.
        New keys may appear without a contract version change.
      example:
        am_wuid: wuid_4o251b0b130v3z6d5q0n
        fbclid: IwAR_sample_fbclid
        utm_source: facebook
      nullable: true
      properties:
        attribution_platform:
          maxLength: 500
          minLength: 1
          type: string
        city:
          maxLength: 500
          minLength: 1
          type: string
        country:
          maxLength: 500
          minLength: 1
          type: string
        country_code:
          maxLength: 500
          minLength: 1
          type: string
        epik:
          maxLength: 500
          minLength: 1
          type: string
        fbc:
          maxLength: 500
          minLength: 1
          type: string
        fbclid:
          maxLength: 500
          minLength: 1
          type: string
        fbp:
          maxLength: 500
          minLength: 1
          type: string
        gbraid:
          maxLength: 500
          minLength: 1
          type: string
        gclid:
          maxLength: 500
          minLength: 1
          type: string
        hyclid:
          maxLength: 500
          minLength: 1
          type: string
        landing_page:
          maxLength: 500
          minLength: 1
          type: string
        li_fat_id:
          maxLength: 500
          minLength: 1
          type: string
        msclkid:
          maxLength: 500
          minLength: 1
          type: string
        rdt_cid:
          maxLength: 500
          minLength: 1
          type: string
        referrer:
          maxLength: 500
          minLength: 1
          type: string
        region:
          maxLength: 500
          minLength: 1
          type: string
        sc_cid:
          maxLength: 500
          minLength: 1
          type: string
        ttclid:
          maxLength: 500
          minLength: 1
          type: string
        twclid:
          maxLength: 500
          minLength: 1
          type: string
        utm_campaign:
          maxLength: 500
          minLength: 1
          type: string
        utm_content:
          maxLength: 500
          minLength: 1
          type: string
        utm_id:
          maxLength: 500
          minLength: 1
          type: string
        utm_medium:
          maxLength: 500
          minLength: 1
          type: string
        utm_source:
          maxLength: 500
          minLength: 1
          type: string
        utm_term:
          maxLength: 500
          minLength: 1
          type: string
        wbraid:
          maxLength: 500
          minLength: 1
          type: string
      type: object
    LeadConsent:
      description: >-
        One consent box and what the person chose: a box on the booking form, or
        Aura's own box for appointment texts.
      example:
        agreed: true
        at: '2026-10-08T10:00:00.000Z'
        disclosure: null
        granted_at: null
        id: 6f1b2c3d-0000-4000-8000-000000000001
        kind: custom
        label: >-
          I agree to receive appointment reminder texts from Acme Inc. Msg &
          data rates may apply. Reply STOP to opt out.
        links:
          - text: SMS Terms
            url: https://example.com/sms-terms
          - text: Privacy Policy
            url: https://example.com/privacy
        phone: '+15551234567'
        source: booking_form
        state: granted
      properties:
        agreed:
          description: >-
            True only while the person agrees and the choice was made for the
            lead's current phone number. False if they never ticked the box,
            unticked it later, replied STOP, or agreed for a different number
            (see `phone`).
          example: true
          type: boolean
        at:
          description: >-
            When the current choice was made (ISO 8601): when they agreed, took
            it back, or finished the form without ticking the box.
          example: '2026-10-08T10:00:00.000Z'
          format: date-time
          type: string
        disclosure:
          description: >-
            The fine print shown beside the box, when it had any. For Aura's box
            for appointment texts: how often texts come, that rates may apply,
            and how to stop them. Null for other boxes.
          example: null
          nullable: true
          type: string
        granted_at:
          description: >-
            For a `withdrawn` box, when they first agreed (ISO 8601). Null for
            every other state.
          example: null
          format: date-time
          nullable: true
          type: string
        id:
          description: >-
            Which box this is, stable when its wording changes: the box's own id
            for a box your team added, `aura_sms` for Aura's box for appointment
            texts, `data_consent` for the data-processing box. Match on this,
            not on `label`.
          example: 6f1b2c3d-0000-4000-8000-000000000001
          type: string
        kind:
          description: >-
            `custom`: a box your team added. `aura_sms`: Aura's own box for
            appointment texts. `data_consent`: the box for using personal data.
          enum:
            - custom
            - data_consent
            - aura_sms
          example: custom
          type: string
        label:
          description: The words on the box, as the person saw them.
          example: >-
            I agree to receive appointment reminder texts from Acme Inc. Msg &
            data rates may apply. Reply STOP to opt out.
          type: string
        links:
          description: The links the box showed, such as SMS terms or a privacy policy.
          items:
            $ref: '#/components/schemas/LeadConsentLink'
          type: array
        phone:
          description: >-
            The phone number this choice was made for. If it is not the lead's
            phone now, `agreed` is false. Null for a choice made before Aura
            kept the number; that choice counts for the lead's phone now.
          example: '+15551234567'
          nullable: true
          type: string
        source:
          description: >-
            How the choice reached Aura. `booking_form`: the booking form.
            `sms_reply_stop` or `sms_reply_start`: the person texted STOP or
            START. `carrier_block`: their phone company blocked texts. `admin`:
            someone on the team changed it. `import`: it came in with imported
            data. Null when Aura did not record how.
          enum:
            - booking_form
            - sms_reply_stop
            - sms_reply_start
            - carrier_block
            - admin
            - import
            - null
          example: booking_form
          nullable: true
          type: string
        state:
          description: >-
            `granted`: they ticked the box. `withdrawn`: they agreed, then took
            it back, by unticking the box or replying STOP. `declined`: they
            finished the form without ticking the box, or said no before they
            ever agreed.
          enum:
            - granted
            - withdrawn
            - declined
          example: granted
          type: string
      required:
        - id
        - kind
        - label
        - disclosure
        - agreed
        - state
        - at
        - granted_at
        - phone
        - source
        - links
      type: object
    DisqualificationData:
      additionalProperties:
        nullable: true
      description: >-
        Snapshot of the form-field state and ruleset that disqualified this lead
        during booking. Null when the lead was not disqualified. See the
        DisqualificationData schema for the full shape.
      nullable: true
      properties:
        archived_at:
          description: ISO 8601 timestamp when the lead was archived.
          type: string
        booking_link_id:
          description: Booking link whose rule produced this disqualification.
          nullable: true
          type: string
        field_key:
          description: >-
            Booking-form field key whose answer triggered disqualification (e.g.
            'budget'). Present when the form disqualification rule produced this
            record.
          type: string
        field_label:
          description: Human-readable label of the triggering field.
          type: string
        reason:
          description: >-
            Free-text reason. Present when the lead was archived rather than
            disqualified by a form rule.
          type: string
        timestamp:
          description: ISO 8601 timestamp when the rule was evaluated.
          example: '2026-05-08T14:23:11.000Z'
          type: string
        value:
          description: The answer the lead gave that triggered disqualification.
          nullable: true
      type: object
    LeadMetadata:
      additionalProperties:
        nullable: true
      description: >-
        Lead attribution + browser + geolocation. JSONB with documented
        camelCase keys (utmSource, utmMedium, fbclid, gclid, referrer, etc.).
        Forward-compatible: unknown keys are accepted and round-trip unchanged.
        See the LeadMetadata schema for the full set of documented fields.
      nullable: true
      properties:
        city:
          description: City name from IP geolocation.
          nullable: true
          type: string
        country:
          description: Country name from IP geolocation.
          nullable: true
          type: string
        countryCode:
          description: ISO 3166-1 alpha-2 country code from IP geolocation.
          example: US
          nullable: true
          type: string
        dataConsentAcceptedAt:
          description: >-
            ISO 8601 timestamp when GDPR data consent was accepted. Generated
            server-side at consent capture.
          example: '2026-05-08T14:23:11.000Z'
          nullable: true
          type: string
        dclid:
          description: Google Display Network click ID.
          nullable: true
          type: string
        epik:
          description: Pinterest click ID.
          nullable: true
          type: string
        fbclid:
          description: >-
            Meta (Facebook + Instagram) click ID. Pixel computes _fbc cookie
            from this.
          nullable: true
          type: string
        gadSource:
          description: Google Ads source attribute (e.g. 'AdWords').
          nullable: true
          type: string
        gbraid:
          description: Google Ads iOS-era click ID.
          nullable: true
          type: string
        gclid:
          description: Google Ads classic click ID.
          nullable: true
          type: string
        gclsrc:
          description: Google Ads source identifier.
          nullable: true
          type: string
        hyclid:
          description: Hyros click ID. Aura's primary attribution platform.
          nullable: true
          type: string
        ipAddress:
          description: Client IP address. Used for geolocation enrichment.
          nullable: true
          type: string
        landingPage:
          description: >-
            Originating landing-page URL (host + pathname, query string
            excluded). Forwarded by the Aura embed script from the host page's
            own location, so two landing pages sharing one booking link and
            identical UTMs stay distinguishable. Unlike `referrer`, this
            preserves the page path. Absent for direct (non-embedded) bookings.
          example: acme.com/sales-manager
          nullable: true
          type: string
        landingUrl:
          description: >-
            The full address of the host page, query string included. Recorded
            by the Aura embed loaders with credentials removed. Like the UTM
            fields it is visitor-supplied attribution, not a verified address; a
            value supplied through this API is stored as sent. Surfaced on the
            lead as `source.landing_url`. Absent for direct (non-embedded)
            bookings.
          example: https://acme.com/sales-manager?utm_source=google&variant=b
          nullable: true
          type: string
        language:
          description: Browser language preference (e.g. 'en-US').
          example: en-US
          nullable: true
          type: string
        latitude:
          description: Latitude from IP geolocation.
          nullable: true
          type: number
        liFatId:
          description: LinkedIn Ads first-party ad tracking ID.
          nullable: true
          type: string
        longitude:
          description: Longitude from IP geolocation.
          nullable: true
          type: number
        msclkid:
          description: Microsoft Ads (Bing) click ID.
          nullable: true
          type: string
        partner:
          description: Partner program name or ID.
          nullable: true
          type: string
        rdtCid:
          description: Reddit click ID.
          nullable: true
          type: string
        ref:
          description: Generic referral code or partner attribution identifier.
          nullable: true
          type: string
        referrer:
          description: >-
            HTTP referrer URL. For embeds, the host page where the booking
            widget was displayed (e.g. 'acme.com/book-a-call'). For direct
            visits, the traffic source URL.
          example: https://acme.com/book-a-call
          nullable: true
          type: string
        region:
          description: Region/state from IP geolocation.
          nullable: true
          type: string
        scCid:
          description: Snapchat click ID.
          nullable: true
          type: string
        screenHeight:
          description: Screen height in pixels.
          nullable: true
          type: number
        screenWidth:
          description: Screen width in pixels.
          nullable: true
          type: number
        setterCode:
          description: >-
            The first setter link code saved for this lead (`?aura_setter=`). It
            may come from a later visit than the lead's first, and it does not
            record who set any call. Use a call's `setter_id` for that.
          nullable: true
          type: string
        ttclid:
          description: TikTok Ads click ID.
          nullable: true
          type: string
        twclid:
          description: X (Twitter) Ads click ID.
          nullable: true
          type: string
        userAgent:
          description: Browser user agent string. Used for device/browser analytics.
          nullable: true
          type: string
        utmCampaign:
          description: >-
            UTM campaign param (e.g. 'summer_promo'). Identifies the specific
            campaign.
          example: spring-2026
          nullable: true
          type: string
        utmContent:
          description: UTM content param. Differentiates ad creatives or A/B test variants.
          nullable: true
          type: string
        utmId:
          description: GA4 utm_id parameter for cross-platform attribution.
          nullable: true
          type: string
        utmMedium:
          description: >-
            UTM medium param (e.g. 'cpc', 'email', 'social'). Identifies the
            marketing channel type.
          example: cpc
          nullable: true
          type: string
        utmSource:
          description: >-
            UTM source param (e.g. 'google', 'facebook'). Identifies the traffic
            platform that drove the lead.
          example: google
          nullable: true
          type: string
        utmTerm:
          description: UTM term param. Paid search keywords or targeting criteria.
          nullable: true
          type: string
        wbraid:
          description: Google Ads web-to-app click ID.
          nullable: true
          type: string
        yclid:
          description: Yandex click ID.
          nullable: true
          type: string
      type: object
    LeadNotes:
      description: >-
        Internal notes attached to the lead, ordered oldest-first. Each note has
        content + created_at + optional user_id. See the LeadNote schema for the
        full shape.
      items:
        $ref: '#/components/schemas/LeadNote'
      nullable: true
      type: array
    LeadConsentLink:
      description: >-
        A link a consent box showed, such as the SMS terms or the privacy
        policy.
      properties:
        text:
          description: The link's words, as the person saw them.
          example: SMS Terms
          type: string
        url:
          description: Where the link went.
          example: https://example.com/sms-terms
          type: string
      required:
        - text
        - url
      type: object
    LeadNote:
      additionalProperties:
        nullable: true
      properties:
        content:
          description: Note body. Plain text or markdown.
          type: string
        created_at:
          description: ISO 8601 timestamp when the note was created.
          example: '2026-05-08T14:23:11.000Z'
          type: string
        user_id:
          description: >-
            ID of the user who created the note. Null for system-generated notes
            (e.g. notes synced from external CRMs via the API).
          nullable: true
          type: string
      required:
        - content
        - created_at
      type: object

````

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