# Creates a new lead with customer details, appointment preferences, and service information.

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /v1/leads:
    post:
      summary: >-
        Creates a new lead with customer details, appointment preferences, and
        service information.
      deprecated: false
      description: >-
        Creates a new lead record in the system.


        **Customer resolution (priority order):**

        1. `customer.existingCustomerId` provided → system looks up the customer
        by FieldEdge ID and uses their stored details; all other customer fields
        are ignored.

        2. `isExistingCustomer = true` → system looks up by phone if provided,
        email if no phone; phone takes priority when both are provided.

        3. New customer → either `customer.email` or `customer.phone` must be
        provided.


        **Required scope:** `leads:write`
      operationId: createLead
      tags:
        - API Documentation/Lead
        - Lead
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/leadRequest'
            example:
              trackingId: null
              source: trane
              preferredContactMethod: phone
              isExistingCustomer: false
              customer:
                customerRefId: db6d3e68-66c1-4504-b9e5-eb9bd1cb4e2b
                firstName: John
                lastName: Doe
                email: john.doe@email.com
                phone: '1234567890'
                marketingEmailOptedIn: true
                address:
                  addressRefId: 3f54d8f3-8a73-47c2-b5ce-0e8a79e39311
                  addressLine1: 123 Main Street
                  addressLine2: Unit 5
                  city: Miami
                  state: FL
                  postalCode: '33101'
                  country: USA
              appointment:
                preferredDate: '2025-07-24'
                preferredTime: '16:24'
                timezone: America/New_York
                availabilityNotes: Available anytime after 4 PM
                location:
                  addressRefId: c1e2d5b0-873b-4f33-9f4c-9b06fb2cd401
                  addressLine1: 456 Service Ave
                  addressLine2: Suite 12
                  city: Orlando
                  state: FL
                  postalCode: '32801'
                  country: USA
              serviceRequest:
                serviceCategory: HVAC
                serviceType: AC Repair
                issueDescription: Air conditioner is not cooling
                image: base64-image-content
                urgency: High
              metaData:
                campaign: SummerPromo2025
                refSource: MobileApp
      responses:
        '201':
          description: Lead created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/leadResponse'
              examples:
                SampleLeadResponse:
                  summary: Sample response returned after creating a lead
                  value:
                    data:
                      leadId: c1e2d5b0-873b-4f33-9f4c-9b06fb2cd401
                      status: Initiated
                      receivedAt: '2025-02-14T10:35:21Z'
          headers: {}
          x-apidog-name: ''
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/fieldErrorResponse'
              examples:
                SampleFieldErrorResponse:
                  summary: Example validation error response
                  value:
                    code: INVALID_INPUT
                    message: One or more fields failed validation.
                    errors:
                      - field: name
                        code: INVALID_VALUE
                        message: The provided value is invalid.
                      - field: requiredField
                        code: REQUIRED
                        message: This field is required.
                    requestId: REQ-12345
                    timestamp: '2025-02-14T10:40:00Z'
          headers: {}
          x-apidog-name: ''
        '401':
          description: Unauthorized — missing or invalid credentials.
          headers: {}
          x-apidog-name: ''
        '403':
          description: Insufficient scope to access this resource.
          content:
            application/json:
              schema: &ref_0
                $ref: '#/components/schemas/errorResponse'
          headers: {}
          x-apidog-name: ''
        '500':
          description: Internal server error
          content:
            application/json:
              schema: *ref_0
              examples:
                SampleErrorResponse:
                  summary: Example generic error response
                  value:
                    statusCode: 500
                    error: Internal Server Error
                    message: Errors occurred while processing the request.
          headers: {}
          x-apidog-name: ''
      security: []
      x-apidog-folder: API Documentation/Lead
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/1204456/apis/api-42492409-run
components:
  schemas:
    leadRequest:
      required:
        - source
        - customer
        - isExistingCustomer
        - appointment
        - serviceRequest
      type: object
      properties:
        trackingId:
          description: Optional tracking identifier for idempotency or traceability.
          type: string
        source:
          description: The source of the lead (e.g., trane, dispatch, customerportal).
          minLength: 1
          type: string
        preferredContactMethod:
          description: >-
            Customer's preferred method of contact.Allowed values: Email, Phone,
            SMS.
          type: string
        customer:
          $ref: '#/components/schemas/leadCustomerRequest'
        isExistingCustomer:
          description: >-
            Set to true if the customer already exists in FieldEdge. The system
            will search by phone number first; if no phone is provided, it will
            search by email. Note: if customer.existingCustomerId is provided,
            this field is ignored.
          type: boolean
        appointment:
          $ref: '#/components/schemas/leadAppointmentRequest'
        serviceRequest:
          $ref: '#/components/schemas/leadServiceRequestRequest'
        metaData:
          description: Optional metadata in key-value format for custom or additional data.
          type: object
          additionalProperties:
            type: string
          x-apidog-orders: []
          properties: {}
          x-apidog-ignore-properties: []
        accountId:
          description: Unique identifier of the account associated with the lead.
          type: string
      x-apidog-orders:
        - trackingId
        - source
        - preferredContactMethod
        - customer
        - isExistingCustomer
        - appointment
        - serviceRequest
        - metaData
        - accountId
      examples:
        - trackingId: null
          source: trane
          preferredContactMethod: phone
          isExistingCustomer: false
          customer:
            customerRefId: db6d3e68-66c1-4504-b9e5-eb9bd1cb4e2b
            firstName: John
            lastName: Doe
            email: john.doe@email.com
            phone: '1234567890'
            marketingEmailOptedIn: true
            address:
              addressRefId: 3f54d8f3-8a73-47c2-b5ce-0e8a79e39311
              addressLine1: 123 Main Street
              addressLine2: Unit 5
              city: Miami
              state: FL
              postalCode: '33101'
              country: USA
          appointment:
            preferredDate: '2025-07-24'
            preferredTime: '16:24'
            timezone: America/New_York
            availabilityNotes: Available anytime after 4 PM
            location:
              addressRefId: c1e2d5b0-873b-4f33-9f4c-9b06fb2cd401
              addressLine1: 456 Service Ave
              addressLine2: Suite 12
              city: Orlando
              state: FL
              postalCode: '32801'
              country: USA
          serviceRequest:
            serviceCategory: HVAC
            serviceType: AC Repair
            issueDescription: Air conditioner is not cooling
            image: base64-image-content
            urgency: High
          metaData:
            campaign: SummerPromo2025
            refSource: MobileApp
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    leadServiceRequestRequest:
      description: Service request details including type, issue description, and urgency.
      type: object
      properties:
        serviceCategory:
          description: Category of the task associated with the service request.
          type: string
        serviceType:
          description: Type of service requested (e.g., HVAC Repair, Plumbing).
          type: string
        issueDescription:
          description: Description of the issue or request.
          type: string
        image:
          description: >-
            Uploaded image related to the service request, represented as a
            binary byte array.
          type: string
        urgency:
          description: Indicates the urgency level of the request.
          type: string
      x-apidog-orders:
        - serviceCategory
        - serviceType
        - issueDescription
        - image
        - urgency
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    leadAppointmentRequest:
      description: Preferred appointment details including date, time, and location.
      type: object
      properties:
        preferredDate:
          description: Preferred appointment date in UTC format (e.g., '2025-07-24').
          type: string
        preferredTime:
          description: >-
            Preferred appointment time in UTC format (24-hour clock, e.g.,
            '16:24').
          type: string
        timezone:
          description: Timezone for the preferred appointment.
          type: string
        availabilityNotes:
          description: Additional notes regarding appointment availability.
          type: string
        location: &ref_1
          $ref: '#/components/schemas/leadAddressRequest'
      x-apidog-orders:
        - preferredDate
        - preferredTime
        - timezone
        - availabilityNotes
        - location
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    leadAddressRequest:
      description: Customer's physical address.
      type: object
      properties:
        addressRefId:
          description: Optional external address reference ID.
          type: string
        addressLine1:
          description: First line of the address.
          type: string
        addressLine2:
          description: Second line of the address (optional).
          type: string
        city:
          description: City name.
          type: string
        state:
          description: State or province.
          type: string
        postalCode:
          description: Postal or ZIP code.
          type: string
        country:
          description: Country name.
          type: string
      x-apidog-orders:
        - addressRefId
        - addressLine1
        - addressLine2
        - city
        - state
        - postalCode
        - country
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    leadCustomerRequest:
      description: Customer information for the lead.
      type: object
      properties:
        existingCustomerId:
          description: >-
            FieldEdge customer ID for an existing customer. When provided, the
            system looks up this customer and uses their stored details,
            ignoring all other customer fields in this request.
          type: string
        customerRefId:
          description: Optional external customer reference ID.
          type: string
        firstName:
          description: Customer's first name.
          type: string
        lastName:
          description: Customer's last name.
          type: string
        email:
          description: >-
            Customer email address. Either email or phone is required for new
            customers.
          type: string
        phone:
          description: >-
            Customer phone number. Either phone or email is required for new
            customers.
          type: string
        address: *ref_1
        marketingEmailOptedIn:
          description: >-
            Indicates whether the customer is MarketingEmailOptedIn for special
            processing or review.
          type: boolean
      x-apidog-orders:
        - existingCustomerId
        - customerRefId
        - firstName
        - lastName
        - email
        - phone
        - address
        - marketingEmailOptedIn
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    leadResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/leadResponseData'
      x-apidog-orders:
        - data
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    leadResponseData:
      description: The lead response data.
      type: object
      properties:
        leadId:
          format: uuid
          description: Unique identifier assigned to the lead.
          type: string
        status:
          format: int32
          description: Current processing status of the lead.
          enum:
            - 0
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
            - 7
            - 8
            - 9
            - 10
            - 11
            - 12
            - 13
            - 14
            - 15
            - 16
            - 17
            - 18
            - 19
          type: integer
        receivedAt:
          format: date-time
          description: The UTC timestamp when the lead was received by the system.
          type: string
      x-apidog-orders:
        - leadId
        - status
        - receivedAt
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    fieldErrorResponse:
      type: object
      properties:
        code:
          description: A short error code representing the type of error.
          type: string
        message:
          description: A descriptive message explaining the error.
          type: string
        errors:
          description: A list of field-specific validation errors, if applicable.
          type: array
          items:
            $ref: '#/components/schemas/fieldErrorDetailResponse'
        requestId:
          description: >-
            A unique identifier associated with the request, useful for
            tracing/debugging.
          type: string
        timestamp:
          description: The timestamp at which the error occurred, in ISO 8601 format.
          type: string
      x-apidog-orders:
        - code
        - message
        - errors
        - requestId
        - timestamp
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    fieldErrorDetailResponse:
      type: object
      properties:
        field:
          description: The name of the field that caused the validation error.
          type: string
        code:
          description: A short error code representing the type of validation failure.
          type: string
        message:
          description: A descriptive message explaining the validation error.
          type: string
      x-apidog-orders:
        - field
        - code
        - message
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    errorResponse:
      type: object
      properties:
        statusCode:
          format: int32
          description: The HTTP status code of the error (e.g., 400, 500).
          type: integer
        error:
          description: A short error identifier or type.
          type: string
        message:
          description: A human-readable message describing the error.
          type: string
        details:
          description: A list of detailed field-specific error information.
          type: array
          items:
            $ref: '#/components/schemas/errorDetailResponse'
      x-apidog-orders:
        - statusCode
        - error
        - message
        - details
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    errorDetailResponse:
      type: object
      properties:
        field:
          description: The name of the field that caused the error.
          type: string
        issue:
          description: A description of the issue related to the field.
          type: string
      x-apidog-orders:
        - field
        - issue
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
  securitySchemes:
    BearerAuth:
      type: jwt
      scheme: bearer
      bearerFormat: JWT
servers:
  - url: https://api.fieldedge.com/open-api
    description: Production
security: []

```