openapi: 3.1.0
info:
  title: LeadSquared REST API
  version: "2.0"
  description: |
    REST API for managing leads, opportunities, and activities in
    LeadSquared. Authentication uses an AccessKey and SecretKey passed
    as query parameters. The API host is region-specific; substitute
    your tenant API host for the {host} server variable.

    Source documentation: https://apidocs.leadsquared.com/
servers:
  - url: https://{host}/v2
    description: Region-specific LeadSquared API host
    variables:
      host:
        default: api.leadsquared.com
        description: Your region-specific API host (see https://apidocs.leadsquared.com/api-host/)
security:
  - AccessKeyAuth: []
    SecretKeyAuth: []
paths:
  /LeadManagement.svc/Lead.Create:
    post:
      operationId: createLead
      summary: Create a lead
      description: |
        Create a new lead in LeadSquared. At least one unique field
        (such as EmailAddress or Phone) must be provided.
      tags:
        - Leads
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/LeadAttribute'
            example:
              - Attribute: EmailAddress
                Value: joe.pesci@example.com
              - Attribute: FirstName
                Value: Joe
              - Attribute: LastName
                Value: Pesci
              - Attribute: Phone
                Value: "8888888888"
      responses:
        '200':
          description: Lead created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateResponse'
              example:
                Status: Success
                Message:
                  Id: cc3fef18-960b-4a60-98c0-af2ab61cee80
  /LeadManagement.svc/Leads.GetById:
    get:
      operationId: getLeadById
      summary: Get a lead by ID
      description: Retrieve a single lead by its unique ProspectID.
      tags:
        - Leads
      parameters:
        - name: id
          in: query
          required: true
          description: Unique identifier of the lead
          schema:
            type: string
      responses:
        '200':
          description: Lead returned (array, possibly empty)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Lead'
        '401':
          description: Invalid credentials
        '429':
          description: Rate limited
  /LeadManagement.svc/Leads.GetByQuickSearch:
    get:
      operationId: quickSearchLeads
      summary: Quick search leads
      description: |
        Search leads by FirstName, LastName, EmailAddress, Phone, Mobile,
        Company, City, or Country. Mirrors the in-app Quick Search box.
      tags:
        - Leads
      parameters:
        - name: key
          in: query
          required: true
          description: Search value
          schema:
            type: string
      responses:
        '200':
          description: Matching leads
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Lead'
  /ProspectActivity.svc/Create:
    post:
      operationId: postActivity
      summary: Post an activity on a lead
      description: |
        Create a custom activity event against a lead. The
        RelatedProspectId identifies the lead, ActivityEvent is the
        configured event code.
      tags:
        - Activities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivityCreate'
            example:
              RelatedProspectId: bd595fc2-3678-4004-9ac6-65bfd1caadb5
              ActivityEvent: 201
              ActivityNote: Your Activity Note
              ProcessFilesAsync: true
              ActivityDateTime: "2015-10-11 12:13:44"
              Fields:
                - SchemaName: mx_Custom_1
                  Value: value
      responses:
        '200':
          description: Activity created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateResponse'
components:
  securitySchemes:
    AccessKeyAuth:
      type: apiKey
      in: query
      name: accessKey
    SecretKeyAuth:
      type: apiKey
      in: query
      name: secretKey
  schemas:
    LeadAttribute:
      type: object
      required:
        - Attribute
        - Value
      properties:
        Attribute:
          type: string
          example: EmailAddress
        Value:
          type: string
          example: joe.pesci@example.com
    CreateResponse:
      type: object
      properties:
        Status:
          type: string
          example: Success
        Message:
          type: object
          properties:
            Id:
              type: string
              example: cc3fef18-960b-4a60-98c0-af2ab61cee80
    Lead:
      type: object
      properties:
        ProspectID:
          type: string
        LeadType:
          type: string
        FirstName:
          type: string
        LastName:
          type: string
        EmailAddress:
          type: string
        Phone:
          type: string
        Company:
          type: string
          nullable: true
        ProspectStage:
          type: string
        OwnerId:
          type: string
        CreatedOn:
          type: string
        ModifiedOn:
          type: string
        Score:
          type: number
        EngagementScore:
          type: number
    ActivityCreate:
      type: object
      required:
        - RelatedProspectId
        - ActivityEvent
      properties:
        RelatedProspectId:
          type: string
        ActivityEvent:
          type: integer
        ActivityNote:
          type: string
        ProcessFilesAsync:
          type: boolean
        ActivityDateTime:
          type: string
          description: Timestamp in "yyyy-mm-dd hh:mm:ss" format
        Fields:
          type: array
          items:
            type: object
            properties:
              SchemaName:
                type: string
              Value:
                type: string
tags:
  - name: Leads
    description: Lead create, get, and search
  - name: Activities
    description: Activity events on leads