Sign in

v1

latestOpenAPI 3.0.3Proprietaryraw.githubusercontent.com2026-03-067260437.0 KB
Clients

List clients

Retrieve a paginated list of clients with powerful filtering capabilities.

gigstack Connect: Access other teams' clients using the team parameter.

Filtering Options:

  • Filter by creation date using comparison operators
  • Filter by metadata fields using dot or underscore notation (e.g., metadata.external_id or metadata_external_id)
get/clients

Query parameters

teamstring

gigstack Connect: Target team ID for multi-team access.

Requires gigstack Connect enabled on your team and shared billing account.

Example: ?team=team_xyz789

limitinteger

Maximum number of items to return (default 50, max 100)

nextstring nullable

Pagination cursor for the next page of results

order_by'name' | 'timestamp'

Field name to order results by

sort'asc' | 'desc'

Sort direction for list queries

Sort direction for the results

integer
OR
string date

Filter results created on or after this timestamp. Accepts Unix timestamp in seconds (e.g., 1733011200), milliseconds (e.g., 1733011200000), or ISO 8601 date string (e.g., 2024-12-01).

integer
OR
string date

Filter results created on or before this timestamp. Accepts Unix timestamp in seconds (e.g., 1735689599), milliseconds (e.g., 1735689599000), or ISO 8601 date string (e.g., 2024-12-31).

metadata.{key}string

Filter by any metadata field using dot notation (e.g., metadata.external_id=EXT-123) or underscore notation (e.g., metadata_external_id=EXT-123). Both formats are supported and equivalent. Uses Typesense search for efficient querying without requiring Firestore indexes.

pageinteger

Page number for pagination when using metadata filters (default 1). Only applies when filtering by metadata fields.

Response

Clients retrieved successfully

messagestring
has_moreboolean
total_resultsinteger
nextstring nullable

Example response

{
  "message": "Clients retrieved successfully",
  "data": [
    {
      "id": "client_1234567890",
      "address": {
        "country": "MEX",
        "street": "Av. Insurgentes Sur",
        "zip": "03100",
        "city": "Ciudad de México",
        "state": "CDMX",
        "exterior": "123",
        "interior": "4B",
        "municipality": "Benito Juárez",
        "neighborhood": "Del Valle"
      },
      "name": "Juan Pérez García",
      "company": "Empresa SA de CV",
      "phone": "+52 55 1234 5678",
      "email": "juan.perez@ejemplo.com",
      "bcc": [
        "admin@empresa.com"
      ],
      "metadata": {
        "custom_field": "value"
      },
      "is_valid": true,
      "from": "api",
      "legal_name": "Juan Pérez García",
      "livemode": true,
      "owner": "user_1234567890",
      "tax_id": "PEGJ800101ABC",
      "use": "P01",
      "tax_system": "601",
      "team": "team_1234567890",
      "created_at": 1677651234,
      "efos": {
        "is_valid": true
      },
      "defaults": {
        "issue_invoiceable_receipts": true
      }
    }
  ],
  "total_results": 25,
  "next": "eyJjcmVhdGVkX2F0IjoxNjc3NjUxMjM0fQ=="
}