List Customers

curl --request POST \
  --url https://api.agents.timepay.ai/api/v1/customers/list \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "campaignId": "<string>",
  "filters": {
    "ids": [
      "<string>"
    ],
    "exclude_ids": [
      "<string>"
    ],
    "phone_number": [
      "<string>"
    ],
    "payment_status": [
      "<string>"
    ],
    "language": [
      "<string>"
    ],
    "custom": {}
  }
}
'

import requests

url = "https://api.agents.timepay.ai/api/v1/customers/list"

payload = {
    "campaignId": "<string>",
    "filters": {
        "ids": ["<string>"],
        "exclude_ids": ["<string>"],
        "phone_number": ["<string>"],
        "payment_status": ["<string>"],
        "language": ["<string>"],
        "custom": {}
    }
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    campaignId: '<string>',
    filters: {
      ids: ['<string>'],
      exclude_ids: ['<string>'],
      phone_number: ['<string>'],
      payment_status: ['<string>'],
      language: ['<string>'],
      custom: {}
    }
  })
};

fetch('https://api.agents.timepay.ai/api/v1/customers/list', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.agents.timepay.ai/api/v1/customers/list",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'campaignId' => '<string>',
    'filters' => [
        'ids' => [
                '<string>'
        ],
        'exclude_ids' => [
                '<string>'
        ],
        'phone_number' => [
                '<string>'
        ],
        'payment_status' => [
                '<string>'
        ],
        'language' => [
                '<string>'
        ],
        'custom' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agents.timepay.ai/api/v1/customers/list"

	payload := strings.NewReader("{\n  \"campaignId\": \"<string>\",\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"phone_number\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.agents.timepay.ai/api/v1/customers/list")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"campaignId\": \"<string>\",\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"phone_number\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agents.timepay.ai/api/v1/customers/list")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"campaignId\": \"<string>\",\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"phone_number\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Customers fetched successfully",
  "data": {
    "campaignId": "lSKmrINyfZEywkpPCaGv",
    "campaignName": "Test api",
    "customers": [
      {
        "loan_id": "LOAN-2026-00001",
        "first_name": "Aarav",
        "last_name": "Sharma",
        "phone_number": "9938177282",
        "loan_amount": "8000",
        "loan_period": "60",
        "emi_amount": "8000",
        "emi_due_date": "2026-02-14",
        "current_emi": "5",
        "payment_status": "received",
        "language": "hindi"
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "campaignId is required and must be a string"
  ]
}

{
  "success": false,
  "error": "Unauthorized",
  "message": "Missing or invalid authorization header"
}

{
  "success": false,
  "error": "Forbidden",
  "message": "You don't have the required permission to perform this action"
}

{
  "success": false,
  "error": "InternalServerError",
  "message": "An unexpected error occurred"
}

List Customers

curl --request POST \
  --url https://api.agents.timepay.ai/api/v1/customers/list \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "campaignId": "<string>",
  "filters": {
    "ids": [
      "<string>"
    ],
    "exclude_ids": [
      "<string>"
    ],
    "phone_number": [
      "<string>"
    ],
    "payment_status": [
      "<string>"
    ],
    "language": [
      "<string>"
    ],
    "custom": {}
  }
}
'

import requests

url = "https://api.agents.timepay.ai/api/v1/customers/list"

payload = {
    "campaignId": "<string>",
    "filters": {
        "ids": ["<string>"],
        "exclude_ids": ["<string>"],
        "phone_number": ["<string>"],
        "payment_status": ["<string>"],
        "language": ["<string>"],
        "custom": {}
    }
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    campaignId: '<string>',
    filters: {
      ids: ['<string>'],
      exclude_ids: ['<string>'],
      phone_number: ['<string>'],
      payment_status: ['<string>'],
      language: ['<string>'],
      custom: {}
    }
  })
};

fetch('https://api.agents.timepay.ai/api/v1/customers/list', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.agents.timepay.ai/api/v1/customers/list",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'campaignId' => '<string>',
    'filters' => [
        'ids' => [
                '<string>'
        ],
        'exclude_ids' => [
                '<string>'
        ],
        'phone_number' => [
                '<string>'
        ],
        'payment_status' => [
                '<string>'
        ],
        'language' => [
                '<string>'
        ],
        'custom' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agents.timepay.ai/api/v1/customers/list"

	payload := strings.NewReader("{\n  \"campaignId\": \"<string>\",\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"phone_number\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.agents.timepay.ai/api/v1/customers/list")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"campaignId\": \"<string>\",\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"phone_number\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agents.timepay.ai/api/v1/customers/list")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"campaignId\": \"<string>\",\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"phone_number\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Customers fetched successfully",
  "data": {
    "campaignId": "lSKmrINyfZEywkpPCaGv",
    "campaignName": "Test api",
    "customers": [
      {
        "loan_id": "LOAN-2026-00001",
        "first_name": "Aarav",
        "last_name": "Sharma",
        "phone_number": "9938177282",
        "loan_amount": "8000",
        "loan_period": "60",
        "emi_amount": "8000",
        "emi_due_date": "2026-02-14",
        "current_emi": "5",
        "payment_status": "received",
        "language": "hindi"
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "campaignId is required and must be a string"
  ]
}

{
  "success": false,
  "error": "Unauthorized",
  "message": "Missing or invalid authorization header"
}

{
  "success": false,
  "error": "Forbidden",
  "message": "You don't have the required permission to perform this action"
}

{
  "success": false,
  "error": "InternalServerError",
  "message": "An unexpected error occurred"
}

Headers

string

required

Bearer token for authentication (e.g., Bearer <your_token>).

string

Optional. Use this header only when the authenticated user belongs to multiple organizations. It identifies the organization to target for this action.

Query Parameters

integer

default:1

The page number for pagination.

Body Parameters

string

required

The unique identifier of the campaign whose customers will be returned.

object

Optional filters to limit the returned customers. Multiple filters are combined with AND logic.

Show properties

string[]

Get specific customers by ID. Use lead_id for lead_generation organizations and loan_id for debt_collection organizations. Maximum 50 IDs.

string[]

Exclude customers by ID. Use lead_id for lead_generation organizations and loan_id for debt_collection organizations.

string[]

Return customers whose phone number matches one of the supplied numbers.

string[]

Return customers whose payment status matches one of the supplied values.

string[]

Return customers whose preferred language matches one of the supplied languages (for example, hindi).

object

Custom field exact-match filters as key-value pairs. Values can be a single string or an array of strings. Use emi_due_date for debt_collection organizations and lead_date for lead_generation organizations.

Example

      {
        "branch": "mumbai",
        "product_type": ["personal_loan", "home_loan"],
        "amount": {"from": 1000, "to": 5000},
        "emi_due_date": "2026-09-14", // for debt_collection organizations
        "lead_date": "2026-08-26" // for lead_generation organizations
      }

Response

boolean

Indicates whether the request was successful.

string

A descriptive message about the result.

object

Customers returned for the campaign.

Show properties

string

The campaign ID used for the request.

string

The name of the campaign.

array

The customer records matching the supplied filters.

object

Pagination details for the result set.

Show properties

integer

Current page number.

integer

Number of customers returned per page. (Always 10)

integer

Total number of matching customers.

integer

Total number of pages available.

boolean

Whether another page is available.

boolean

Whether a previous page is available.

{
  "success": true,
  "message": "Customers fetched successfully",
  "data": {
    "campaignId": "lSKmrINyfZEywkpPCaGv",
    "campaignName": "Test api",
    "customers": [
      {
        "loan_id": "LOAN-2026-00001",
        "first_name": "Aarav",
        "last_name": "Sharma",
        "phone_number": "9938177282",
        "loan_amount": "8000",
        "loan_period": "60",
        "emi_amount": "8000",
        "emi_due_date": "2026-02-14",
        "current_emi": "5",
        "payment_status": "received",
        "language": "hindi"
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 2,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "campaignId is required and must be a string"
  ]
}

{
  "success": false,
  "error": "Unauthorized",
  "message": "Missing or invalid authorization header"
}

{
  "success": false,
  "error": "Forbidden",
  "message": "You don't have the required permission to perform this action"
}

{
  "success": false,
  "error": "InternalServerError",
  "message": "An unexpected error occurred"
}

Error Codes

Status	Description
`400`	Validation error - `campaignId` is required
`401`	Unauthorized - missing or invalid authorization header
`403`	Forbidden - insufficient permission to access the campaign customers
`500`	Internal server error

​Headers

​Query Parameters

​Body Parameters

​Response

​Error Codes

Headers

Query Parameters

Body Parameters

Response

Error Codes