SmartMatchApp

List All Clients

Retrieve a list of clients, sorted by creation date, with the most recent clients appearing first.

This endpoint returns a list of clients. By default, only the client IDs are returned, but you can specify which fields to display in the response using the field parameter. The results can also be filtered using profile and preference fields, similar to the structure in the profile and preferences update endpoints.

Example Request:
# Basic request to list clients
curl "https://<your-agency>.smartmatchapp.com/api3/clients/" \
    -u <token>: \
    -X GET

# Get client list with filters

curl "https://<your-agency>.smartmatchapp.com/api3/clients/?prof_1=text&pref_1_start=5" \
    -u <token>: \
    -X GET

curl "https://<your-agency>.smartmatchapp.com/api3/clients/?lists=1&lists=2" \
    -u <token>: \
    -X GET

# Use count and offset for pagination
curl "https://<your-agency>.smartmatchapp.com/api3/clients/?count=50&offset=10" \
    -u <token>: \
    -X GET
Request Parameters:
Pagination:

count: (Optional) The number of results to display in the response (default is 20).

offset: (Optional) The offset from the beginning of the list.

Note: count and offset in the response echo the values you requested, not the size of the returned page. The last page can contain fewer than count items — compare offset plus the length of objects against total_count to detect the end of the list.

Field Selection:

field: (Optional) Use this parameter to specify which fields to display in the response. You can specify up to 10 fields.

Example: ?field=prof_1&field=prof_2

Filtering:

Profile and preference fields can be used as filters, following the same structure as the profile and preferences update endpoints.

Example: ?pref_1_start=1&prof_1_country=UA

Example Success Response:
{
    "total_count": 2,
    "count": 2,
    "offset": 0,
    "objects": [
        {
            "id": 1,
            "is_archived": false,
            "is_submitted": false,
            "stype": {
                "id": 2,
                "name": "Retailer"
            },
            "prof_1": "text"
        },
        {
            "id": 2,
            "is_archived": false,
            "is_submitted": false,
            "stype": {},
            "prof_1": "text"
        }
    ]
}
Base Request:

Method: GET

Authentication: Basic Authentication. Requires a valid <token> passed.

Rate Limits:

30 requests within 5 seconds

Error Responses:
400 Bad Request

This error occurs if the provided filters or field names are invalid.
Possible errors: "Select a valid choice. That choice is not one of the available choices."
401 Unauthorized

This error occurs when the <token> is missing, invalid, or the API access is disabled.

Possible errors: "not authenticated" or "token is disabled" or "Agency API is disabled"
404 Not Found

This error occurs if the requested resource or clients with the specified filters do not exist.
Possible errors: "resource not found"
405 Method Not Allowed

This error occurs if an HTTP method other than GET is used (e.g., POST or PUT).
Possible errors: "wrong method"
429 Too Many Requests

This error occurs when the client has sent too many requests in a given amount of time, leading to rate limiting by the server.

Possible errors: "too many requests"
500 Server Error

Possible errors: "Internal server error"
Available Fields:

The field ids, labels, types, and available values below are generic samples. Every agency defines its own custom fields, so your agency's own live list appears in its private copy of these API docs.

Title Name Type
id Integer Number
Archived is_archived Yes/No
Submitted is_submitted Yes/No
Type stype
Show Values
  • 1: Example Client Type
Lists lists
Show Values
  • 1: Example List
Profile Fields
First Name prof_1 Text
Country prof_2 Select
Show Values
  • 1: Example value A
  • 2: Example value B
Preferences Fields
Age pref_1 Range
Country pref_2 Select
Show Values
  • 1: Example value A
  • 2: Example value B