> ## Documentation Index
> Fetch the complete documentation index at: https://agents.docs.timepay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Customer

> Add a single customer record to an existing campaign with optional immediate call initiation.

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication (e.g., `Bearer <your_token>`).
</ParamField>

### Body Parameters

<ParamField body="campaignId" type="string" required>
  Target campaign ID. The campaign must already exist.
</ParamField>

<ParamField body="data" type="object" required>
  Customer data object. The required fields depend on your campaign's service type.

  <Tabs>
    <Tab title="Debt Collection">
      **Use this structure if you are managing existing loans.**

      <Expandable title="item properties">
        <ParamField body="loan_id" type="string" required>Unique identifier for the loan record.</ParamField>
        <ParamField body="first_name" type="string" required>Customer's first name.</ParamField>
        <ParamField body="last_name" type="string" required>Customer's last name.</ParamField>
        <ParamField body="phone_number" type="string" required>Customer's primary contact number.</ParamField>
        <ParamField body="loan_amount" type="number" required>Total principal amount of the loan.</ParamField>
        <ParamField body="emi_amount" type="number" required>EMI amount due for the current billing cycle.</ParamField>
        <ParamField body="loan_period" type="number" required>Total loan tenure in monthly installments.</ParamField>
        <ParamField body="current_emi" type="number" required>Current installment number in the repayment schedule (e.g., 5 of 12).</ParamField>
        <ParamField body="emi_due_date" type="string" required>Due date for the current EMI. Format: `YYYY-MM-DD`.</ParamField>

        <ParamField body="payment_status" type="string" required>
          Current status of the customer's EMI payment.

          <Expandable title="options">
            * `bounced` — Payment was attempted but failed (e.g., insufficient funds).
            * `pending` — Payment is due but not yet initiated.
            * `partial` — Customer has made a partial payment.
            * `paid` — Payment has been completed by the customer.
            * `received` — Payment has been received and confirmed.
          </Expandable>
        </ParamField>

        <ParamField body="language" type="string">Preferred language for the AI agent (e.g., `english`, `hindi`, `tamil`).</ParamField>
      </Expandable>
    </Tab>

    <Tab title="Lead Generation">
      **Use this structure for new sales or lead acquisition.**

      <Expandable title="item properties">
        <ParamField body="lead_id" type="string">Unique identifier for the lead. Auto-generated (UUID) if not provided.</ParamField>
        <ParamField body="first_name" type="string" required>Customer's first name.</ParamField>
        <ParamField body="last_name" type="string" required>Customer's last name.</ParamField>
        <ParamField body="phone_number" type="string" required>Customer's primary contact number.</ParamField>
        <ParamField body="lead_date" type="string" required>Date the lead was captured. Format: `YYYY-MM-DD`.</ParamField>
        <ParamField body="language" type="string">Preferred language for the AI agent (e.g., `english`, `hindi`, `tamil`).</ParamField>
      </Expandable>
    </Tab>
  </Tabs>
</ParamField>

<ParamField body="initiateCall" type="boolean" default={false}>
  If `true`, initiates a call to the customer immediately after adding. Requires `callConfig`. Cannot be `true` if `useWorkflow` is `true`.
</ParamField>

<ParamField body="callConfig" type="object">
  Required when `initiateCall` is `true`.

  <Expandable title="properties">
    <ParamField body="agentId" type="string" required>AI agent ID to handle the call.</ParamField>
    <ParamField body="dispositionId" type="string" required>Disposition ID for call categorization.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="useWorkflow" type="boolean" default={false}>
  If `true`, triggers workflow execution asynchronously. Cannot be `true` if `initiateCall` is `true`.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates whether the request was successful.
</ResponseField>

<ResponseField name="message" type="string">
  A descriptive message about the result.
</ResponseField>

<ResponseField name="data" type="object">
  Details of the added customer.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      The document ID (`loan_id` or `lead_id`) of the added customer.
    </ResponseField>

    <ResponseField name="campaignId" type="string">
      The campaign the customer was added to.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="callInitiated" type="boolean">
  Whether the call was successfully initiated. Only present when `initiateCall` was `true`.
</ResponseField>

<ResponseField name="callError" type="string">
  Reason the call could not be initiated. Only present when `callInitiated` is `false`.
</ResponseField>

<ResponseField name="workflowTriggered" type="boolean">
  Whether the workflow execution was triggered. Only present when `useWorkflow` was `true`.
</ResponseField>

<ResponseExample>
  ```json 201 Added (without call) theme={null}
  {
    "success": true,
    "message": "Customer added to campaign successfully",
    "data": {
      "id": "LOAN-2025-00123",
      "campaignId": "camp_abc123"
    }
  }
  ```

  ```json 201 Added (with call initiated) theme={null}
  {
    "success": true,
    "message": "Customer added and call initiated successfully",
    "data": {
      "id": "LOAN-2025-00456",
      "campaignId": "camp_abc123"
    },
    "callInitiated": true
  }
  ```

  ```json 201 Added (with workflow triggered) theme={null}
  {
    "success": true,
    "message": "Customer added and workflow triggered successfully",
    "data": {
      "id": "LOAN-2025-00456",
      "campaignId": "camp_abc123"
    },
    "workflowTriggered": true
  }
  ```

  ```json 201 Added (call failed) theme={null}
  {
    "success": true,
    "message": "Customer added successfully but call could not be initiated: No active numbers available",
    "data": {
      "id": "LOAN-2025-00456",
      "campaignId": "camp_abc123"
    },
    "callInitiated": false,
    "callError": "No active numbers available for this organization"
  }
  ```

  ```json 400 Validation Error theme={null}
  {
    "success": false,
    "message": "Validation failed",
    "errors": [
      "Record 0: Missing required field 'phone_number'",
      "Record 0: Missing required field 'emi_due_date'"
    ]
  }
  ```

  ```json 404 Campaign Not Found theme={null}
  {
    "success": false,
    "message": "Campaign not found"
  }
  ```

  ```json 409 Duplicate Customer theme={null}
  {
    "success": false,
    "message": "Customer with loan_id 'LOAN-2025-00123' already exists in this campaign."
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "success": false,
    "message": "Campaign ID invalid or mismatch for your organization."
  }
  ```

  ```json 500 Server Error theme={null}
  {
    "success": false,
    "error": "Internal Server Error",
    "message": "An unexpected error occurred"
  }
  ```
</ResponseExample>