openapi: 3.0.3
info:
  title: Telecrm Public APIs
  version: 1.0.0
  description: |-
    The Telecrm Public APIs can be used to push data to Telecrm from any source. This is useful when Telecrm doesn't provide native integrations for your current platform/CRM. You can perform operations on the following entities:
      
      * **Leads**: Potential or existing customers of your enterprise
      * **Actions:** Operations that can be performed on a lead. (Call, Text, Email, Payment)

    ## Authentication 
    All requests to the API must include an authentication token as a Bearer Token in the request headers. Follow the steps below to generate the token:
    1. Go to the Integration Page in Telecrm.
    2. Open Website Integration.
    3. Click on "Integrate Website"
    4. Click on "Generate New Token"
    5. Enter a Token Name to identify the token
    6. Click "Create" to generate the token
    7. Once the token is created, click on "Copy Token" to copy the token to the clipboard. It is recommended to also download the token and keep it secure.
    ## API Names
    Find the API names of fields in the "Lead Fields" section of the Telecrm app:
    1. Click a field.
    2. Click the "Information" dropdown to view its API name. 
servers:
  - url: https://next.telecrm.in/autoupdate/v2
    description: Production
security:
  - BearerAuth: []
tags:
  - name: leads
    description: Operations on leads
  - name: actions
    description: 'Operations on a lead''s actions. NOTE: Only **custom actions** and **payment actions** are currently supported.'
  - name: team-members
    description: Operations on team members
  - name: enterprise
    description: Retrieve enterprise metadata
  - name: team-members
    description: Operations on team members
paths:
  /enterprise/{enterpriseId}/lead/{leadId}:
    parameters:
      - $ref: '#/components/parameters/enterpriseId'
      - $ref: '#/components/parameters/leadId'
    get:
      tags:
        - leads
      summary: Get an existing lead
      description: Get an existing lead by ID. Optionally include a paginated list of actions on the lead by setting `includeActions=true`.
      parameters:
        - in: query
          name: includeActions
          schema:
            type: boolean
            default: false
          description: If set to `true`, includes a paginated list of actions on the lead. If `false` or not provided, actions are omitted.
        - in: query
          name: skip
          schema:
            type: integer
            default: 0
            minimum: 0
          description: Number of actions to skip for pagination. Only applicable when `includeActions=true`.
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
          description: Maximum number of actions to return. Only applicable when `includeActions=true`.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lead'
        '400':
          description: Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: BAD_REQUEST
                  message: Limit should be between 1 and 100
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Lead was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: LEAD_NOT_FOUND
                  message: The lead with ID 62ab16e was not found.
    post:
      tags:
        - leads
      summary: Update a lead
      description: Update a lead by ID
      requestBody:
        description: Lead body
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InputLeadUpdate'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadNoAction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Cannot modify lead identifier field
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INVALID_LEAD
                  message: Cannot modify lead identifier field
        '404':
          description: Lead with given ID was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: LEAD_NOT_FOUND
                  message: Lead with ID 62ab16e was not found.
  /enterprise/{enterpriseId}/lead:
    parameters:
      - $ref: '#/components/parameters/enterpriseId'
    post:
      tags:
        - leads
      summary: Create a lead
      description: Create a lead in your enterprise
      requestBody:
        description: Lead body
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InputLead'
            examples:
              with-custom-action:
                summary: Lead with a custom action
                value:
                  fields:
                    name: Jane Doe
                    phone: '919999999999'
                  actions:
                    - type: '1001'
                      fields:
                        note: Site visit completed
              basic:
                summary: Lead without actions
                value:
                  fields:
                    name: Jane Doe
                    phone: '919999999999'
      responses:
        '201':
          description: Lead was successfully created. However, one or more actions on the lead may not have been created due to invalid action body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  lead_id:
                    type: string
                  actions:
                    type: array
                    items:
                      $ref: '#/components/schemas/CreateActionResponse'
                  remarks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Remark'
                    description: Remarks for lead creation
                example:
                  - lead_id: 603d2b2f9b1e8a001c8e4f5c
                    actions:
                      - action_id: 603d2b2f9b1e8a001c8e4f5c
                        status: CREATED
                      - action_id: null
                        status: IGNORED
                    remarks:
                      - field: fields.rating
                        status: IGNORED
                        remark: Rating must be between 1 and 5
                      - field: actions[0].fields.email
                        status: IGNORED
                        remark: Email is invalid
        '400':
          description: Invalid lead body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: INVALID_LEAD
                  message: Lead identifier field name 'phone' not found in request body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Lead already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: LEAD_ALREADY_EXISTS
                  message: Lead with phone 91999999999 already exists.
  /enterprise/{enterpriseId}/lead/search:
    parameters:
      - $ref: '#/components/parameters/enterpriseId'
      - in: query
        name: skip
        schema:
          description: Number of leads to skip
          type: number
          default: 0
      - in: query
        name: limit
        schema:
          description: Number of leads to return
          type: number
          default: 10
          minimum: 1
          maximum: 100
    post:
      tags:
        - leads
      summary: Search for leads
      description: Search for leads by various filters. Searches are **case-insensitive** and require **exact matches**.
      requestBody:
        description: Search body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchLead'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchLeadResults'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: Rating value must be between 1 and 5
        '401':
          $ref: '#/components/responses/Unauthorized'
  /enterprise/{enterpriseId}/lead/{leadId}/action/{actionId}:
    parameters:
      - $ref: '#/components/parameters/enterpriseId'
      - $ref: '#/components/parameters/leadId'
      - $ref: '#/components/parameters/actionId'
    get:
      tags:
        - actions
      summary: Get an action
      description: Get an action on a lead by ID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadAction'
        '400':
          description: Invalid action type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: BAD_REQUEST
                  message: Only custom actions and payment actions can be retrieved
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Resource was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: ACTION_NOT_FOUND
                  message: Action with ID 62ab16e was not found.
    post:
      tags:
        - actions
      summary: Update an action
      description: Update an action on a lead by ID. Please note that only the **status** field can be updated for payment actions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLeadAction'
            examples:
              custom-action:
                summary: Update a custom action
                value:
                  type: '1001'
                  fields:
                    note: Follow-up completed
              payment-action:
                summary: Update a payment action status
                value:
                  type: PAYMENT
                  status: PAID
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadAction'
        '400':
          description: Bad request - invalid action type or immutable fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                immutable-payment-fields:
                  value:
                    error:
                      code: BAD_REQUEST
                      message: Cannot update amount, currency, or paymentid fields for existing payment action.
                invalid-action-type:
                  value:
                    error:
                      code: BAD_REQUEST
                      message: Only custom actions and payment actions can be retrieved
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Resource was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: ACTION_NOT_FOUND
                  message: Action with ID 62ab16e was not found in the lead.
  /enterprise/{enterpriseId}/lead/{leadId}/action:
    parameters:
      - $ref: '#/components/parameters/enterpriseId'
      - $ref: '#/components/parameters/leadId'
    post:
      tags:
        - actions
      summary: Create actions
      description: Create actions on a lead by ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                actions:
                  type: array
                  items:
                    $ref: '#/components/schemas/InputLeadAction'
              required:
                - actions
            examples:
              custom-action:
                summary: Create a custom action
                value:
                  actions:
                    - type: '1001'
                      fields:
                        note: Site visit completed
              payment-action:
                summary: Create a payment action
                value:
                  actions:
                    - type: PAYMENT
                      status: PAID
                      currency: INR
                      amount: 5000
      responses:
        '200':
          description: Actions created successfully on the lead, though some may have failed due to validation errors.
          content:
            application/json:
              schema:
                type: object
                properties:
                  lead_id:
                    type: string
                  actions:
                    type: array
                    items:
                      $ref: '#/components/schemas/CreateActionResponse'
                example:
                  - lead_id: 603d2b2f9b1e8a001c8e4f5c
                    actions:
                      - action_id: 603d2b2f9b1e8a001c8e4f5c
                        status: CREATED
                      - action_id: null
                        status: IGNORED
                    remarks:
                      - field: actions[0].fields.email
                        status: IGNORED
                        remark: Email is invalid
                      - field: actions[1].fields.phone
                        status: IGNORED
                        remark: Phone number is invalid
        '400':
          description: Invalid action type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: BAD_REQUEST
                  message: Only custom actions and payment actions can be retrieved
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Lead with given ID was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: LEAD_NOT_FOUND
                  message: Lead with ID 62ab16e was not found.
  /enterprise/{enterpriseId}/lead/{leadId}/action/search:
    parameters:
      - $ref: '#/components/parameters/enterpriseId'
      - $ref: '#/components/parameters/leadId'
    post:
      tags:
        - actions
      summary: Search for actions
      description: Search for actions on a lead
      requestBody:
        description: Search body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchLeadAction'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchLeadActionResults'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Lead with given ID was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /enterprise/{enterpriseId}/teammember/state_change:
    post:
      summary: Team member availability
      description: Sets team member availability in the system.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                state:
                  type: string
                  description: State of the team member.
                email:
                  type: string
                  description: The team member whose email.
              required:
                - state
                - email
      responses:
        '200':
          description: Team member status updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    description: Email of the team member whose state is changed.
                  status:
                    type: string
                    description: Updated status of the team member.
        '400':
          description: Invalid request payload.
  /enterprise/{enterpriseId}/team-members:
    parameters:
      - $ref: '#/components/parameters/enterpriseId'
    get:
      tags:
        - team-members
      summary: List team members
      description: Retrieve a paginated list of team members in the enterprise. Results are sorted in ascending order by name.
      parameters:
        - in: query
          name: skip
          schema:
            type: integer
            default: 0
            minimum: 0
          description: Number of team members to skip for pagination.
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 10
          description: Maximum number of team members to return. Must be between 1 and 10.
        - in: query
          name: includeDeleted
          schema:
            type: boolean
            default: false
          description: If `true`, includes deleted team members in the results. If `false` or not provided, only active, inactive, and invited members are returned.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamMemberList'
        '400':
          description: Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: BAD_REQUEST
                  message: Limit should be between 1 and 10
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
        - team-members
      summary: Create a team member
      description: Create a new team member in your enterprise
      requestBody:
        description: Team member details
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTeamMemberRequest'
      responses:
        '201':
          description: Team member was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTeamMemberResponse'
        '400':
          description: Validation failed. One or more fields are invalid or missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing-required-fields:
                  value:
                    error:
                      code: BAD_REQUEST
                      message: Validation failed
                      details:
                        - field: name
                          message: name is required
                        - field: email
                          message: email is required
                invalid-role:
                  value:
                    error:
                      code: BAD_REQUEST
                      message: Validation failed
                      details:
                        - field: role
                          message: 'Invalid role. Allowed roles: ADMIN, MANAGER, CALLER, MARKETING_USER'
                invalid-email:
                  value:
                    error:
                      code: BAD_REQUEST
                      message: Validation failed
                      details:
                        - field: email
                          message: Invalid email format
                invalid-phone:
                  value:
                    error:
                      code: BAD_REQUEST
                      message: Validation failed
                      details:
                        - field: phone_number
                          message: Invalid phone_number format. Please provide a valid phone number with country code (e.g. 919876543210)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: License seat limit reached. Purchase additional licenses to add more team members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: BUY_LICENSE
                  message: License seat limit reached
        '403':
          description: Not authorized to create team members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_AUTHORIZED
                  message: Not authorized
  /enterprise/{enterpriseId}/team-members/{email}:
    parameters:
      - $ref: '#/components/parameters/enterpriseId'
      - $ref: '#/components/parameters/teamMemberEmail'
    get:
      tags:
        - team-members
      summary: Get a team member by email
      description: Retrieve a single team member by their email address.
      parameters:
        - in: query
          name: includeDeleted
          schema:
            type: boolean
            default: false
          description: If `true`, returns the team member even if they have been deleted. If `false` or not provided, deleted members return 404.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamMemberResponse'
        '400':
          description: Invalid email format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: BAD_REQUEST
                  message: Invalid email format
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Team member was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: TEAM_MEMEBER_NOT_FOUND
                  message: Team member not found
  /enterprise/{enterpriseId}/custom-fields:
    parameters:
      - $ref: '#/components/parameters/enterpriseId'
    get:
      tags:
        - enterprise
      summary: Get all custom fields
      description: Retrieve all custom fields defined in the enterprise. Use the `detail` query parameter to control the level of detail in the response.
      parameters:
        - in: query
          name: detail
          schema:
            type: boolean
            default: false
          description: If set to `true`, returns detailed field definitions including options for dropdowns, tags, and date formats. If `false` or not provided, returns a summary view with basic field information only.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFields'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Enterprise was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: ENTERPRISE_NOT_FOUND
                  message: the enterprise with iD 62ab16e was not found.
  /enterprise/{enterpriseId}/custom-fields/{apiName}:
    parameters:
      - $ref: '#/components/parameters/enterpriseId'
      - $ref: '#/components/parameters/fieldApiName'
    get:
      tags:
        - enterprise
      summary: Get a custom field by API name
      description: Retrieve a specific custom field definition by its unique API name
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldDetailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Custom field with the given API name was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: Could not find custom field with apiName contact_source
  /enterprise/{enterpriseId}/custom-actions:
    parameters:
      - $ref: '#/components/parameters/enterpriseId'
    get:
      tags:
        - enterprise
      summary: Get all custom actions
      description: Retrieve all custom actions defined in the enterprise. Use the `detail` query parameter to control the level of detail in the response.
      parameters:
        - in: query
          name: detail
          schema:
            type: boolean
            default: false
          description: If set to `true`, returns detailed custom action definitions including all fields, schemas, and metadata. If `false` or not provided, returns a summary view with basic information (code, displayName, score, source) only.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomActions'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Enterprise was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: ENTERPRISE_NOT_FOUND
                  message: the enterprise with iD 62ab16e was not found.
  /enterprise/{enterpriseId}/custom-actions/{code}:
    parameters:
      - $ref: '#/components/parameters/enterpriseId'
      - $ref: '#/components/parameters/customActionCode'
    get:
      tags:
        - enterprise
      summary: Get a custom action by code
      description: Retrieve a specific custom action definition by its unique code
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomActionDetailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Custom action with the given code was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: NOT_FOUND
                  message: Custom action with code ACTION_1001 was not found.
  /enterprise/{enterpriseId}/metadata:
    parameters:
      - $ref: '#/components/parameters/enterpriseId'
    get:
      tags:
        - enterprise
      summary: Get enterprise metadata
      description: Retrieve metadata information about the enterprise including name, industry, team size, and integrations
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnterpriseMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Enterprise was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: ENTERPRISE_NOT_FOUND
                  message: the enterprise with iD 62ab16e was not found.
  /enterprise/{enterpriseId}/lead-stage-pipeline:
    parameters:
      - $ref: '#/components/parameters/enterpriseId'
    get:
      tags:
        - enterprise
      summary: Get lead stage pipeline
      description: Retrieve the complete lead stage pipeline configuration including all stages, statuses, and lost reasons. This includes both active and archived statuses and lost reasons.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadStagePipeline'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Enterprise was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: ENTERPRISE_NOT_FOUND
                  message: the enterprise with iD 62ab16e was not found.
components:
  schemas:
    TeamMemberResponse:
      type: object
      properties:
        name:
          type: string
          nullable: true
          description: Full name of the team member.
          example: Jane Doe
        email:
          type: string
          nullable: true
          description: Email address of the team member.
          example: jane.doe@example.com
        status:
          type: string
          nullable: true
          description: Current availability status of the team member.
          enum:
            - Active
            - Inactive
            - On Leave
            - Working
            - Invited
            - Deleted
          example: Working
        phone_number:
          type: string
          nullable: true
          description: WhatsApp/phone number of the team member.
          example: '919999999999'
        manager_name:
          type: string
          nullable: true
          description: Full name of the team member's direct manager.
          example: John Smith
        manager_email:
          type: string
          nullable: true
          description: Email address of the team member's direct manager.
          example: john.smith@example.com
        permission_template_name:
          type: string
          nullable: true
          description: Name of the permission template assigned to the team member.
          example: Sales Agent
        license:
          type: object
          nullable: true
          description: Most recent license assigned to the team member. `null` if no license exists.
          allOf:
            - $ref: '#/components/schemas/TeamMemberLicense'
    TeamMemberLicense:
      type: object
      properties:
        status:
          type: string
          description: Current status of the license (e.g. ACTIVE, EXPIRED).
          example: ACTIVE
        type:
          type: string
          description: License plan type.
          example: GROWTH
        start_date:
          description: Date from which the license is valid.
          example: '2024-01-01'
        end_date:
          description: Date on which the license expires.
          example: '2025-01-01'
    TeamMemberList:
      type: object
      description: Paginated list of team members sorted in ascending order by name.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TeamMemberResponse'
        total_count:
          type: number
          description: Total number of team members matching the query.
          example: 42
        skip:
          type: number
          description: Number of team members skipped.
          example: 0
        limit:
          type: number
          description: Maximum number of team members returned.
          example: 10
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    CreateActionResponse:
      type: object
      properties:
        action_id:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - CREATED
            - IGNORED
    Remark:
      type: object
      properties:
        field:
          type: string
          example: actions[0].fields.email
        status:
          type: string
          enum:
            - IGNORED
            - WARNING
            - ERROR
          example: IGNORED
        remark:
          type: string
          example: Email is invalid
    InputLead:
      required:
        - fields
      properties:
        fields:
          $ref: '#/components/schemas/InputLeadFields'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/InputLeadAction'
    InputLeadUpdate:
      description: 'Contains the values of the fields to be updated. Note: the leadId cannot be updated'
      required:
        - fields
      properties:
        fields:
          $ref: '#/components/schemas/UpdateLeadFields'
    SearchLeadResults:
      type: object
      description: Results are sorted in descending order of creation timestamp. (newest first)
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/LeadNoAction'
        total_count:
          type: number
          example: 1
        skip:
          type: number
        limit:
          type: number
          example: 10
    SearchLead:
      type: object
      properties:
        fields:
          type: object
          properties:
            name:
              oneOf:
                - $ref: '#/components/schemas/TextField'
                - type: array
                  items:
                    $ref: '#/components/schemas/TextField'
              example:
                - John Doe
                - Jane Doe
            phone:
              oneOf:
                - $ref: '#/components/schemas/PhoneField'
                - type: array
                  items:
                    $ref: '#/components/schemas/PhoneField'
              example:
                - '919999999999'
                - '919999999998'
            rating:
              oneOf:
                - $ref: '#/components/schemas/RatingField'
                - type: array
                  items:
                    $ref: '#/components/schemas/RatingField'
              example:
                - 3
                - 4
            status:
              oneOf:
                - $ref: '#/components/schemas/StatusField'
                - type: array
                  items:
                    $ref: '#/components/schemas/StatusField'
              example:
                - Won
                - Lost
            assignee:
              oneOf:
                - $ref: '#/components/schemas/EmailField'
                - type: array
                  items:
                    $ref: '#/components/schemas/EmailField'
              example:
                - john.doe@example.com
                - jane.doe@example.com
            created_on:
              type: object
              properties:
                from:
                  $ref: '#/components/schemas/DateField'
                to:
                  $ref: '#/components/schemas/DateField'
              example:
                from: 1/1/2001
                to: 2/2/2002
          additionalProperties:
            description: |
              - All those fields that are defined in the workspace. Defined as api name of the field, and its corresponding valid value based on type.
            anyOf:
              - oneOf:
                  - $ref: '#/components/schemas/PhoneField'
                  - type: array
                    items:
                      $ref: '#/components/schemas/PhoneField'
              - oneOf:
                  - $ref: '#/components/schemas/StatusField'
                  - type: array
                    items:
                      $ref: '#/components/schemas/StatusField'
              - oneOf:
                  - $ref: '#/components/schemas/MoneyField'
                  - type: array
                    items:
                      $ref: '#/components/schemas/MoneyField'
              - oneOf:
                  - $ref: '#/components/schemas/TagsField'
                  - type: array
                    items:
                      $ref: '#/components/schemas/TagsField'
              - oneOf:
                  - $ref: '#/components/schemas/EmailField'
                  - type: array
                    items:
                      $ref: '#/components/schemas/EmailField'
              - oneOf:
                  - $ref: '#/components/schemas/RatingField'
                  - type: array
                    items:
                      $ref: '#/components/schemas/RatingField'
              - oneOf:
                  - $ref: '#/components/schemas/TextField'
                  - type: array
                    items:
                      $ref: '#/components/schemas/TextField'
              - type: object
                properties:
                  from:
                    $ref: '#/components/schemas/DateField'
                  to:
                    $ref: '#/components/schemas/DateField'
              - oneOf:
                  - $ref: '#/components/schemas/DropdownField'
                  - type: array
                    items:
                      $ref: '#/components/schemas/DropdownField'
              - oneOf:
                  - $ref: '#/components/schemas/NumberField'
                  - type: array
                    items:
                      $ref: '#/components/schemas/NumberField'
              - oneOf:
                  - $ref: '#/components/schemas/WebsiteField'
                  - type: array
                    items:
                      $ref: '#/components/schemas/WebsiteField'
              - oneOf:
                  - $ref: '#/components/schemas/LostReasonField'
                  - type: array
                    items:
                      $ref: '#/components/schemas/LostReasonField'
        actions:
          type: object
          description: Filter leads by their action history. All criteria must be satisfied by the same action on the lead (AND logic).
          properties:
            type:
              description: Action type(s) to filter by. Accepts a single value or an array. Custom actions can be referenced by their numeric ID (e.g., "1001"). See the `type` field in `SearchLeadAction` for the full list of valid values.
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
              example:
                - INCOMING_CALL
                - OUTGOING_CALL
            performed_by:
              description: Team member email(s) who performed the action. Accepts a single email or an array.
              oneOf:
                - $ref: '#/components/schemas/EmailField'
                - type: array
                  items:
                    $ref: '#/components/schemas/EmailField'
              example: agent@company.com
            performed_at:
              type: object
              description: Time range in which the action was performed. Each bound accepts a Unix millisecond timestamp or a date-time string in any common format (e.g., "01/01/2025", "2025-01-31T23:59:59", "31-01-2025 23:59:59"). When the timezone is ambiguous the workspace default timezone is used.
              properties:
                from:
                  $ref: '#/components/schemas/CreatedOnField'
                to:
                  $ref: '#/components/schemas/CreatedOnField'
    CustomFields:
      properties:
        customFields:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              apiName:
                type: string
              lockAfterCreate:
                type: boolean
              isLeadid:
                type: boolean
                description: Indicates whether this field is the unique identifier field for the enterprise
              options:
                type: array
                items:
                  type: string
              tags:
                type: array
                items:
                  type: string
            required:
              - type
              - apiName
              - lockAfterCreate
    CustomFieldDetailed:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the custom field
        type:
          type: string
          description: Type of the custom field
          enum:
            - TEXT
            - NUMBER
            - EMAIL
            - PHONE
            - DATE
            - DROPDOWN
            - TAGS
            - MONEY
            - WEBSITE
            - UNIQUE
          example: DROPDOWN
        apiName:
          type: string
          description: API name used to reference this field
          example: contact_source
        description:
          type: string
          description: Description of the custom field
        lockAfterCreate:
          type: boolean
          description: Whether the field is locked after creation
          example: false
        isLeadid:
          type: boolean
          description: Indicates whether this field is the unique identifier field for the enterprise
          example: false
        options:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              label:
                type: string
          description: Options for dropdown fields
        tags:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              label:
                type: string
          description: Tags for tag fields
        dateFormat:
          type: string
          description: Date format for date fields
          example: DD/MM/YYYY
        timeFormat:
          type: string
          description: Time format for date fields
          example: HH:mm
      required:
        - id
        - type
        - apiName
    CustomActions:
      type: object
      properties:
        customActions:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/CustomActionSummary'
              - $ref: '#/components/schemas/CustomActionDetailed'
          description: Array of custom action definitions. When detail=false, returns summary objects with basic fields only. When detail=true, returns detailed objects with complete action definition including schemas and metadata.
    CustomActionSummary:
      type: object
      properties:
        code:
          type: string
          description: Unique code identifying the custom action
          example: ACTION_1001
        displayName:
          type: string
          description: Display name of the custom action
          example: Site Visit
        score:
          type: number
          description: Score/weight assigned to this action
          example: 10
        source:
          type: string
          description: Source of the custom action definition
          enum:
            - SYSTEM
            - USER
          example: USER
      required:
        - code
        - displayName
        - score
        - source
    CustomActionDetailed:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the custom action
        displayName:
          type: string
          description: Display name of the custom action
          example: Site Visit
        icon:
          type: string
          description: Icon identifier for the action
        description:
          type: string
          description: Description of the custom action
        code:
          type: string
          description: Unique code identifying the custom action
          example: ACTION_1001
        score:
          type: number
          description: Score/weight assigned to this action
          example: 10
        fieldSchema:
          type: object
          description: Schema defining the fields for this custom action
          additionalProperties: true
        displaySchema:
          type: object
          description: Schema defining how the action should be displayed
          additionalProperties: true
        allowPredatedActivity:
          type: object
          description: Configuration for allowing backdated activities
          additionalProperties: true
        quickAdd:
          type: object
          description: Configuration for quick add functionality
          additionalProperties: true
        definitionType:
          type: string
          description: Type of the custom action definition
        createdOn:
          type: number
          description: Timestamp when the action was created
          example: 1609459200000
        createdBy:
          type: string
          description: User who created the action
        modifiedOn:
          type: number
          description: Timestamp when the action was last modified
          example: 1609459200000
        modifiedBy:
          type: string
          description: User who last modified the action
        source:
          type: string
          description: Source of the custom action definition
          enum:
            - SYSTEM
            - USER
          example: USER
      required:
        - id
        - code
        - displayName
        - source
    EnterpriseMetadata:
      type: object
      properties:
        name:
          type: string
          description: Name of the enterprise
          example: Acme Corporation
        id:
          type: string
          description: Unique identifier of the enterprise
          example: ent_123456
        creationTimeStamp:
          type: number
          description: Timestamp when the enterprise was created
          example: 1609459200000
        teamSize:
          type: string
          description: Size of the team
          example: 50-100
        industry:
          type: string
          description: Industry the enterprise operates in
          example: Technology
        website:
          type: string
          description: Enterprise website URL
          example: https://acme.com
        leadIdentifierFieldId:
          type: string
          description: ID of the field used as the lead identifier
          example: phone
        integrations:
          type: array
          items:
            type: string
          description: List of active integrations
          example:
            - WHATSAPP
            - EMAIL
            - SMS
      required:
        - name
        - id
    LeadStagePipeline:
      type: object
      properties:
        leadStages:
          type: array
          items:
            $ref: '#/components/schemas/LeadStage'
          description: Array of lead stages in the pipeline
        activeLeadLostReasons:
          type: array
          items:
            $ref: '#/components/schemas/LeadLostReason'
          description: Currently active lost reasons
        archivedLeadLostReasons:
          type: array
          items:
            $ref: '#/components/schemas/LeadLostReason'
          description: Archived lost reasons
        creationTimestamp:
          type: number
          description: Timestamp when the pipeline was created
          example: 1609459200000
        modificationTimestamp:
          type: number
          description: Timestamp when the pipeline was last modified
          example: 1609459200000
        lastModifiedBy:
          type: string
          description: User who last modified the pipeline
        version:
          type: number
          description: Version number of the pipeline
          example: 1
      required:
        - leadStages
    LeadStage:
      type: object
      properties:
        stageid:
          type: string
          description: Unique identifier of the stage
        stageType:
          type: string
          description: Type of the lead stage
          enum:
            - OPEN
            - WON
            - LOST
        visibility:
          type: boolean
          description: Whether the stage is visible
        activeStatuses:
          type: array
          items:
            $ref: '#/components/schemas/LeadStatus'
          description: Currently active statuses in this stage
        archivedStatuses:
          type: array
          items:
            $ref: '#/components/schemas/LeadStatus'
          description: Archived statuses in this stage
      required:
        - stageid
        - stageType
    LeadStatus:
      type: object
      properties:
        statusid:
          type: number
          description: Unique identifier of the status
          example: 1
        label:
          type: string
          description: Display label for the status
          example: New Lead
        color:
          type: string
          description: Color code for the status
          example: '#FF5733'
      required:
        - statusid
        - label
    LeadLostReason:
      type: object
      properties:
        reasonid:
          type: number
          description: Unique identifier of the lost reason
          example: 1
        reasonLabel:
          type: string
          description: Label describing the lost reason
          example: Price too high
        isDefault:
          type: boolean
          description: Whether this is the default lost reason
          example: false
      required:
        - reasonid
        - reasonLabel
    CreateTeamMemberRequest:
      type: object
      required:
        - name
        - email
        - phone_number
        - role
      properties:
        name:
          type: string
          description: Full name of the team member
          example: John Doe
        email:
          type: string
          format: email
          description: Email address of the team member
          example: john.doe@example.com
        phone_number:
          type: string
          description: Phone number with country code (e.g. 919876543210)
          example: '919876543210'
        role:
          type: string
          description: Role to assign to the team member
          enum:
            - ADMIN
            - MANAGER
            - CALLER
            - MARKETING_USER
          example: CALLER
        password:
          type: string
          description: Optional password for the team member. If not provided, an invite will be sent.
          example: securePassword123
    CreateTeamMemberResponse:
      type: object
      properties:
        name:
          type: string
          description: Name of the created team member
          example: John Doe
        email:
          type: string
          description: Email of the created team member
          example: john.doe@example.com
        phone_number:
          type: string
          description: Phone number of the created team member
          example: '919876543210'
        role:
          type: string
          description: Assigned role
          example: CALLER
        status:
          type: string
          description: Current status of the team member
          example: INVITED
    LeadNoAction:
      properties:
        fields:
          $ref: '#/components/schemas/LeadFields'
    Lead:
      properties:
        fields:
          $ref: '#/components/schemas/LeadFields'
        actions:
          type: array
          items:
            $ref: '#/components/schemas/LeadAction'
          description: Paginated list of actions. Only present when `includeActions=true`.
        actions_skip:
          type: integer
          description: The skip value used for action pagination. Only present when `includeActions=true`.
          example: 0
        actions_limit:
          type: integer
          description: The limit value used for action pagination. Only present when `includeActions=true`.
          example: 10
    LeadAction:
      anyOf:
        - $ref: '#/components/schemas/CustomAction'
        - $ref: '#/components/schemas/PaymentAction'
    InputLeadAction:
      anyOf:
        - $ref: '#/components/schemas/InputCustomAction'
        - $ref: '#/components/schemas/InputPaymentAction'
    UpdateLeadAction:
      anyOf:
        - $ref: '#/components/schemas/UpdateCustomAction'
        - $ref: '#/components/schemas/UpdatePaymentAction'
    SearchLeadAction:
      type: object
      properties:
        type:
          type: string
          description: Action type to search for. Custom action codes are defined in Workspace Settings -> Custom Actions.
          enum:
            - '1001'
            - '1002'
            - '1003'
            - MISSED_CALL
            - INCOMING_CALL
            - MAQSAM_INCOMING_CALL
            - IVR_INCOMING_CALL
            - MCUBE_INCOMING_CALL
            - OUTGOING_CALL
            - MCUBE_OUTGOING_CALL
            - OUTGOING_SMS
            - OUTGOING_WHATSAPP_MSG
            - OUTGOING_EMAIL
            - MAQSAM_OUTGOING_CALL
            - IVR_OUTGOING_CALL
            - SYSTEM_NOTE
            - USER_NOTE
            - CALL_REMINDER_CREATION
            - TIME_FOR_CALL
            - DELAY_REMINDER_CREATION
            - TIME_FOR_DELAY_COMPLETION
            - MARKED_DONE
            - INCOMING_WHATSAPP_MSG
            - PAYMENT
            - FIELD_CHANGE
            - LEAD_ASSIGNMENT
            - ATTACHMENT
            - CAMPAIGN_SKIPPED_ACTION
            - UNSUPPORTED_ACTION
            - LOCATION_CHECK_IN_ACTION
            - LEAD_MERGE
            - RAZORPAY
            - CUSTOM_API
            - GOOGLE_SHEET
            - HOUSING
            - EXCEL_BULK_EDIT
            - KNOWLARITY_INCOMING_CALL
            - KNOWLARITY_OUTGOING_CALL
            - CALLER_DESK_INCOMING_CALL
            - CALLER_DESK_OUTGOING_CALL
            - STATUS_CHANGE
            - LEAD_ARCHIVE
            - LEAD_RESTORE
            - LEAD_OTP
            - TASK_CREATION_ACTION
            - CALL_FOLLOWUP_COMPLETION_ACTION
            - TODO_TASK_COMPLETION_ACTION
            - GOOGLE_MEET_COMPLETION_ACTION
            - DELETE_LEAD
            - TRADE_INDIA_ACTION
            - FACEBOOK
            - MAGIC_BRICKS_ACTION
            - NINETY_NINE_ACRES_ACTION
            - LEAD_SPAM_ACTION
            - AUTO_UPDATE_LEAD_ACTION
            - SALES_FLOW_ACTION
            - SHOPIFY
            - JUSTDIAL
            - SULEKHA
            - CALL_ACTION
            - WHATSAPP_ACTION
            - RESTORE_LEAD
            - PAYMENT
        created_on:
          type: object
          properties:
            from:
              $ref: '#/components/schemas/CreatedOnField'
            to:
              $ref: '#/components/schemas/CreatedOnField'
        performed_by:
          description: Filter actions by the member(s) who performed them. Accepts a single member ID or an array of member IDs.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
    SearchLeadActionResults:
      type: object
      description: Results are sorted in descending order of creation timestamp. (newest first)
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/LeadAction'
        total_count:
          type: number
          example: 1
        skip:
          type: number
        limit:
          type: number
          example: 10
    InputPaymentAction:
      allOf:
        - $ref: '#/components/schemas/PaymentAction'
      required:
        - type
        - status
        - currency
        - amount
    UpdatePaymentAction:
      description: '- Cannot update amount, currency or paymentid fields. - Only payment status can be updated.'
      allOf:
        - $ref: '#/components/schemas/PaymentAction'
    InputCustomAction:
      allOf:
        - $ref: '#/components/schemas/CustomActionWithCreatedOn'
      required:
        - type
    UpdateCustomAction:
      allOf:
        - $ref: '#/components/schemas/CustomAction'
      required:
        - type
    CustomAction:
      type: object
      description: |
        - Only custom actions defined in the workspace will be processed.
        - One of the fields must be the type of the custom action
      properties:
        type:
          type: string
          description: Custom action code defined in Workspace Settings -> Custom Actions
          example: '1001'
        fields:
          type: object
          additionalProperties:
            description: |
              - All custom fields defined in the custom action. Defined as api name of the field, and its corresponding valid value based on type.
            anyOf:
              - $ref: '#/components/schemas/TextField'
              - $ref: '#/components/schemas/DateField'
              - $ref: '#/components/schemas/DropdownField'
              - $ref: '#/components/schemas/NumberField'
              - $ref: '#/components/schemas/ActiveUsersField'
              - $ref: '#/components/schemas/MedialinkField'
    CustomActionWithCreatedOn:
      allOf:
        - $ref: '#/components/schemas/CustomAction'
        - type: object
          properties:
            created_on:
              $ref: '#/components/schemas/CreatedOnField'
    PaymentAction:
      type: object
      properties:
        type:
          type: string
          enum:
            - PAYMENT
        status:
          $ref: '#/components/schemas/PaymentStatusField'
        currency:
          $ref: '#/components/schemas/PaymentCurrencyField'
        amount:
          allOf:
            - description: Payment amount must be greater than 0
            - $ref: '#/components/schemas/MoneyField'
        created_on:
          $ref: '#/components/schemas/CreatedOnField'
    InputLeadFields:
      allOf:
        - $ref: '#/components/schemas/LeadFields'
      description: |
        - One of the fields must be the unique identifier field (default: phone)
        - Only lead fields defined in the workspace will be processed.
    UpdateLeadFields:
      allOf:
        - $ref: '#/components/schemas/LeadFields'
      description: |
        - Only lead fields defined in the workspace will be processed.
        - The unique identifier field (default: phone) cannot be updated.
    LeadFields:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/TextField'
        phone:
          $ref: '#/components/schemas/PhoneField'
        email:
          $ref: '#/components/schemas/EmailField'
        rating:
          $ref: '#/components/schemas/RatingField'
        status:
          $ref: '#/components/schemas/StatusField'
        assignee:
          description: Email address should be of an employee in the workspace
          $ref: '#/components/schemas/EmailField'
      additionalProperties:
        description: |
          - All those fields that are defined in the workspace. Defined as api name of the field, and it's corresponding valid value based on type.
        anyOf:
          - $ref: '#/components/schemas/PhoneField'
          - $ref: '#/components/schemas/EmailField'
          - $ref: '#/components/schemas/RatingField'
          - $ref: '#/components/schemas/StatusField'
          - $ref: '#/components/schemas/MoneyField'
          - $ref: '#/components/schemas/TagsField'
          - $ref: '#/components/schemas/TextField'
          - $ref: '#/components/schemas/DateField'
          - $ref: '#/components/schemas/DropdownField'
          - $ref: '#/components/schemas/NumberField'
          - $ref: '#/components/schemas/WebsiteField'
          - $ref: '#/components/schemas/LostReasonField'
    TextField:
      type: string
      description: Text field with optional length constraints
      example: John
    PhoneField:
      type: string
      description: Phone number with international country code (e.g. +91 for India). If country code is not specified, enterprise's default country code will be used.
      example: '+91999999999'
    EmailField:
      type: string
      format: email
      description: Valid email address
      example: john.doe@example.com
    RatingField:
      type: integer
      description: Rating value between 1 and 5
      minimum: 1
      maximum: 5
      example: 3
    StatusField:
      type: string
      description: Lead status value. Must be one of the statuses defined in the workspace's lead stage pipeline. Defaults to 'Fresh'.
      example: Fresh
    MoneyField:
      type: string
      description: Value must be a valid currency amount in the workspace's currency
      example: '1000'
    TagsField:
      type: array
      items:
        type: string
      description: If the value does not match one of the predefined tags in the workspace, it will be created. Maximum 1000 tags allowed. Each value has 40 chars limit.
      example:
        - Tag1
        - Tag2
    DateField:
      type: string
      format: date-time
      description: |
        Unix timestamp or date-time in workspace-defined format. Time defaults to 00:00:00 if omitted. **Values in other formats may not be processed correctly.**
      example: 01/01/2023 10:30:00
    DropdownField:
      type: string
      description: If the value does not match one of the predefined options in the workspace, it will be created. Maximum 1000 options. Each value has 40 chars limit.
    NumberField:
      type: number
      description: Valid number
      example: '156'
    WebsiteField:
      allOf:
        - description: Valid website link
        - $ref: '#/components/schemas/TextField'
    LostReasonField:
      type: string
      description: Reason for losing the lead. Must be one of the lost reasons defined in the workspace's lead stage pipeline. Defaults to 'Unknown Reason
      example: No Need
    ActiveUsersField:
      allOf:
        - description: 'Email address should be of an employee in the workspace. '
        - $ref: '#/components/schemas/EmailField'
    MedialinkField:
      allOf:
        - $ref: '#/components/schemas/TextField'
        - description: Valid media link
    PaymentStatusField:
      type: string
      example: PENDING
      enum:
        - PENDING
        - COMPLETED
        - FAILED
        - REFUNDED
        - CANCELLED
        - PROCESSING
    PaymentCurrencyField:
      type: string
      enum:
        - INR
        - USD
        - PKR
        - AED
        - QAR
        - SAR
        - MYR
        - AUD
        - CAD
        - SGD
        - XOF
    CreatedOnField:
      type: string
      format: date-time
      description: |
        Unix timestamp or date-time in DD/MM/YYYY HH:mm:ss format. Time component defaults to 00:00:00 if omitted. **Values in other formats may not be processed correctly.**

        If not specified, the current timestamp is set.

        Field is ignored for non-predated actions.
      example: 01/01/2023 11:30:00
  responses:
    Unauthorized:
      description: Invalid access token/Wrong enterprise ID
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: NOT_AUTHORIZED
              message: Enterprise with ID 51ab23c9870 not found or invalid access token. Please generate a new one from the Website/API integrations section of the Telecrm app.
  parameters:
    enterpriseId:
      in: path
      name: enterpriseId
      required: true
      schema:
        type: string
      description: Id of the enterprise
    leadId:
      in: path
      name: leadId
      schema:
        type: string
      required: true
      description: Id of the lead
    actionId:
      in: path
      name: actionId
      schema:
        type: string
      required: true
      description: Id of the action
    customActionCode:
      in: path
      name: code
      schema:
        type: string
      required: true
      description: Unique code of the custom action (e.g., ACTION_1001)
    fieldApiName:
      in: path
      name: apiName
      schema:
        type: string
      required: true
      description: API name of the custom field (e.g., contact_source, deal_size)
    teamMemberEmail:
      in: path
      name: email
      schema:
        type: string
      required: true
      description: Email address of the team member
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer