Docs API Reference Contact/bff/contact/list

getContactAdmin BFF

/bff/contact/list

Returns a paginated list of contacts/customers with vitals, group membership, newsletter status, and CRM analytics. Supports full-text search, group filtering, and 10 attribute filters. All boolean filters use string values ("true"/"false"). Pagination via limit/page query params.

ContactgetBffContactList

Parameters

16 query

Query parameters

· 16

limitnumberOptional

Example0

pagenumberOptional

Example0

filterFulltextQuerystringOptional

Full-text search across name, email, phone, and company name.

Examplejan@example.com

tagFilterstringOptional

Comma-separated customer group slugs. Use "#-no-tags-#" for untagged contacts.

Examplevip,wholesale

orderBystringOptional

Sort field and direction. Format: "field:asc" or "field:desc".

Examplecredit:desc

isPremiumstringOptional

Filter VIP/premium customers.

Exampletrue

isBannedstringOptional

Filter blocked/banned customers.

Exampletrue

isRegisteredstringOptional

Filter by registration status (has password = registered account).

Exampletrue

isTestAccountstringOptional

Filter test accounts. Use "false" to exclude them from reports.

Exampletrue

hasCreditstringOptional

Filter customers with positive credit balance ("true") or zero credit ("false").

Exampletrue

localestringOptional

Filter by customer locale.

Examplecs

registeredFromstringOptional

Filter customers registered on or after this date (inclusive).

Example2026-01-01

registeredTostringOptional

Filter customers registered on or before this date (inclusive).

Example2026-01-31

lastActivityFromstringOptional

Filter customers active on or after this date. Use to find recently active or inactive users.

Example2026-01-01

ignoreBulkMailstringOptional

Filter by bulk email opt-out status. "true" = opted out, "false" = subscribed.

Exampletrue

isSuspiciousstringOptional

Filter contacts flagged by the automated cleanup routine as suspicious / non-functional.

Exampletrue

Response schema

1 status code documented

200SuccessPaginated contact list with CRM analytics.

itemsobject[]Required

Each array item:

idstringRequired

Contact external ID (16-char).

emailstring | nullRequired

One of 2:

Variant 1

string

Primary e-mail. null for phone-only contacts (imported by phone with no e-mail) and for contacts anonymised via GDPR right-to-erasure. Use phone, name, or the external ID for display when null.

Variant 2

null

namestringOptional

Full display name (first + last).

firstNamestringOptional

First name.

lastNamestringOptional

Last name.

companyNamestringOptional

Company name.

isCompanybooleanOptional

True if the contact has company registration data attached.

companyRegistrationNumberstringOptional

IČO / company registration number.

taxIdentificationNumberstringOptional

DIČ / VAT / tax identification number.

isVatPayerbooleanOptional

Whether the contact is currently a VAT payer (from registry).

isUnreliableVatPayerbooleanOptional

Flagged as unreliable VAT payer by the tax authority.

phonestringOptional

Phone number.

localestringRequired

Customer locale code (cs, en, de…).

newsletter"registered" | "authorized" | "canceled" | "ignored" | nullOptional

One of 2:

Variant 1

"registered" | "authorized" | "canceled" | "ignored"

Newsletter subscription status.

Variant 2

null

ignoreBulkMailbooleanRequired

Opted out of bulk emails.

testAccountbooleanOptional

Is a test account.

premiumbooleanOptional

VIP/premium customer flag.

banbooleanOptional

Blocked/banned customer flag.

registeredbooleanRequired

Has a password (registered account).

creditnumberRequired

Current store credit balance.

creditMoneynumberRequired

Current store credit balance in default currency (CZK).

defaultOrderSalenumberRequired

Default order discount for this customer.

subscriptionActiveCountnumberOptional

Number of active subscriptions (computed from subscription table).

groupListobject[]Required

Customer group memberships.

Each array item:

slugstringRequired

Group slug identifier.

namestringRequired

Group display name.

colorstringRequired

Group color hex code.

countnumberOptional

Number of contacts in this group.

avatarUrlstringOptional

Gravatar URL.

internalNotestringOptional

Internal admin note.

insertedDateDate | string | string | numberRequired

Registration date.

One of 4:

Variant 1

Date

Registration date.

Variant 2

stringdate-time

Variant 3

stringdate

Variant 4

number

updatedDateDate | string | string | numberRequired

Last profile update date.

One of 4:

Variant 1

Date

Last profile update date.

Variant 2

stringdate-time

Variant 3

stringdate

Variant 4

number

lastActivityDateDate | string | string | numberRequired

Last activity timestamp.

One of 4:

Variant 1

Date

Last activity timestamp.

Variant 2

stringdate-time

Variant 3

stringdate

Variant 4

number

accountAgeDaysnumberRequired

Days since registration.

monthLimitMaxCreditSpendHardnumberRequired

Hard monthly credit spend limit.

monthLimitMaxCreditSpendSoftnumberRequired

Soft monthly credit spend limit (warning threshold).

orderPaidnumberRequired

Number of paid orders.

orderNotPaidnumberRequired

Number of unpaid orders.

orderNewnumberRequired

Orders in "new" status.

orderProcessingnumberRequired

Orders in "processing" status.

orderStornonumberRequired

Orders in "storno" status (from vitals).

orderDonenumberRequired

Orders in "done" status.

scorenumberRequired

CRM quality score (0–100). Higher = better customer.

totalRevenuenumberRequired

Lifetime revenue from paid orders.

paidOrderCountnumberRequired

Total number of paid orders (materialized).

refundTotalnumberRequired

Total value of refunded/storno items.

firstOrderDatestringOptional

Date of first order (ISO timestamp).

lastOrderDatestringOptional

Date of most recent order (ISO timestamp).

lastPaidOrderDatestringOptional

Date of most recent paid order (ISO timestamp).

stornoOrderCountnumberRequired

Number of cancelled/storno orders.

voucherOrderCountnumberRequired

Number of orders placed with a voucher.

activeSubscriptionCountnumberRequired

Number of active subscriptions (materialized).

badgesobject | object[]Required

Display-ready badge list (operator, ban, premium, company, VAT flags, reverse charge, tax exempt, test account, subscription, suspicious) plus user-defined group tags. Same order and contents as the contact detail and hover popover — use directly in the UI.

Each array item:

object | object

One of 2:

Variant 1

kind"system"Required

Variant 2

kind"group"Required

slugstringRequired

namestringRequired

colorstringRequired

suspiciousobjectOptional

Present when the contact is currently flagged by the automated cleanup routine. Absent otherwise.

reasonCodestringRequired

Machine-readable reason slug (translated by admin).

reasonLabelstringRequired

English fallback label from the reason registry.

severity"info" | "warning" | "critical"Required

flaggedDatestringRequired

ISO timestamp when the flag was set.

registeredStatus"none" | "active" | "inactive"Optional

Three-state registration status: "none" — no account, "active" — has account and is not banned / suspicious, "inactive" — has account but is banned or suspicious.

itemCountnumberRequired

Total number of contacts matching the filter (before pagination).

Response example

application/json

{
  "items": [
    {
      "id": "example_id",
      "name": "example_name",
      "firstName": "example_firstName",
      "lastName": "example_lastName",
      "companyName": "example_companyName",
      "isCompany": false,
      "companyRegistrationNumber": "example_companyRegistrationNumber",
      "taxIdentificationNumber": "example_taxIdentificationNumber",
      "isVatPayer": false,
      "isUnreliableVatPayer": false,
      "phone": "example_phone",
      "locale": "example_locale",
      "ignoreBulkMail": false,
      "testAccount": false,
      "premium": false,
      "ban": false,
      "registered": false,
      "credit": 0,
      "creditMoney": 0,
      "defaultOrderSale": 0,
      "subscriptionActiveCount": 0,
      "groupList": [
        {
          "slug": "example_slug",
          "name": "example_name",
          "color": "example_color",
          "count": 0
        }
      ],
      "avatarUrl": "example_avatarUrl",
      "internalNote": "example_internalNote",
      "accountAgeDays": 0,
      "monthLimitMaxCreditSpendHard": 0,
      "monthLimitMaxCreditSpendSoft": 0,
      "orderPaid": 0,
      "orderNotPaid": 0,
      "orderNew": 0,
      "orderProcessing": 0,
      "orderStorno": 0,
      "orderDone": 0,
      "score": 0,
      "totalRevenue": 0,
      "paidOrderCount": 0,
      "refundTotal": 0,
      "firstOrderDate": "example_firstOrderDate",
      "lastOrderDate": "example_lastOrderDate",
      "lastPaidOrderDate": "example_lastPaidOrderDate",
      "stornoOrderCount": 0,
      "voucherOrderCount": 0,
      "activeSubscriptionCount": 0,
      "badges": [],
      "suspicious": {
        "reasonCode": "example_reasonCode",
        "reasonLabel": "example_reasonLabel",
        "flaggedDate": "example_flaggedDate"
      }
    }
  ],
  "itemCount": 0
}

Request example

GET /bff/contact/list

get

curl -X GET "https://api.bizkithub.com/bff/contact/list?limit=0&page=0&filterFulltextQuery=jan%40example.com&tagFilter=vip%2Cwholesale&orderBy=credit%3Adesc&isPremium=true&isBanned=true&isRegistered=true&isTestAccount=true&hasCredit=true&locale=cs&registeredFrom=2026-01-01&registeredTo=2026-01-31&lastActivityFrom=2026-01-01&ignoreBulkMail=true&isSuspicious=true" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Need an API key?

All BizKitHub public API endpoints require authentication via API key.

Get API Key