openapi: 3.0.3
info:
  title: Defiant Law Lead Intake API
  version: 1.0.0
  description: |
    Secure lead submission API for approved Defiant Law referral partners.
    The production Power Automate SAS-signed endpoint is provided separately
    and must be treated as a confidential credential.
  contact:
    name: Isaac Ramirez
    email: Jonathan@defiant-law.com
servers:
  - url: https://PARTNER-SPECIFIC-POWER-AUTOMATE-ENDPOINT
    description: Replace with the complete SAS-signed endpoint provided securely
paths:
  /:
    post:
      operationId: createLead
      summary: Create a referral lead
      description: Submits one lead to Defiant Law's intake system.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadRequest'
            example:
              externalLeadId: LGT-123456
              firstName: John
              lastName: Doe
              phone: '9095551234'
              email: john.doe@example.com
              state: CA
              bestTime: Afternoon
              preferredLanguage: English
              campaign: California Solar Campaign
              notes: Customer requested an afternoon callback.
              submittedAt: '2026-07-27T21:30:00Z'
      responses:
        '201':
          description: Lead created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid or incomplete request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Duplicate external lead ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: One or more fields failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              schema:
                type: integer
                example: 60
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal processing error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    LeadRequest:
      type: object
      required:
        - firstName
        - lastName
        - phone
        - email
        - state
      properties:
        externalLeadId:
          type: string
          description: Unique identifier assigned by the referral partner.
          maxLength: 150
        firstName:
          type: string
          minLength: 1
          maxLength: 100
        lastName:
          type: string
          minLength: 1
          maxLength: 100
        phone:
          type: string
          minLength: 7
          maxLength: 30
        email:
          type: string
          format: email
          maxLength: 254
        state:
          type: string
          enum: [AZ, CA, NM, NV, TX]
        bestTime:
          type: string
          maxLength: 100
        preferredLanguage:
          type: string
          enum: [English, Spanish]
        campaign:
          type: string
          maxLength: 250
        notes:
          type: string
          maxLength: 4000
        submittedAt:
          type: string
          format: date-time
    SuccessResponse:
      type: object
      required: [success, intakeId, message]
      properties:
        success:
          type: boolean
          example: true
        intakeId:
          type: string
          example: lgt-a63f1358-79db-4f3b-9d23-8f26994a4852
        message:
          type: string
          example: Lead created.
    ErrorDetail:
      type: object
      properties:
        field:
          type: string
          example: state
        message:
          type: string
          example: 'State must be one of: AZ, CA, NM, NV, or TX.'
    ErrorResponse:
      type: object
      required: [success, error]
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: One or more fields failed validation.
            details:
              type: array
              items:
                $ref: '#/components/schemas/ErrorDetail'