Clients

Clients endpoints of the Zanfia Workspace API, with schemas and code samples.

17 min readLast updated Oct 16, 2026

Manage contacts and product access. Adding a client creates a contact only — access is granted per product. Marketing consent is separate for email and SMS and can be set in bulk (POST /clients/email-subscription, POST /clients/sms-subscription, up to 200 clients per call). Tags are managed under /clients/tags (create, rename/recolour, delete) and assigned in bulk with POST /clients/tags/assignments; a newly added tag fires the client.TagAdded workflow trigger. All routes require a Authorization: Bearer header — see Authentication.

List clients

GET/clients

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Query Parameters

createdFrom?string

"Date added" window start, inclusive: an ISO 8601 date-time, or YYYY-MM-DD (the start of that day, UTC). Same filter as the Customers list in the dashboard; also accepted by GET /clients/export.

createdTo?string

"Date added" window end, inclusive: an ISO 8601 date-time, or YYYY-MM-DD (the whole day, UTC). Must not be before createdFrom; a malformed value answers 400.

Response Body

`application/json`

curl -X GET "https://example.com/clients"

{  "items": [    {      "id": "string",      "email": "string",      "firstName": "string",      "lastName": "string",      "phoneNumber": "string",      "totalOrders": 0,      "totalSpentCents": 0,      "activeProducts": 0,      "language": "string",      "discordId": "string",      "githubId": 0,      "tagIds": [        "string"      ],      "emailSubscriptionStatus": "pending",      "attribution": {        "utmSource": "string",        "utmMedium": "string",        "utmCampaign": "string",        "utmTerm": "string",        "utmContent": "string",        "fbclid": "string",        "gclid": "string",        "metaCampaignId": "string",        "metaAdId": "string",        "metaCampaignName": "string",        "metaAdName": "string",        "capturedAt": "string"      },      "customFields": {        "property1": "string",        "property2": "string"      },      "createdAt": "string"    }  ],  "nextCursor": "string"}

{  "error": "string",  "message": "string"}

Add a client (contact only)

POST/clients

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Create a CONTACT-ONLY client — a workspace customer with no product grant and no order. Granting product access is a separate action (not exposed here yet).

email*string

firstName?string

lastName?string

phoneNumber?string|null

language?string|null

marketingConsent?boolean

Marketing e-mail consent for this client (source integration). Absent: the key's own setting decides („Klienci dodani tym kluczem dostają zgodę marketingową”). true on a key without that setting needs consentStatement: true. false: no consent from this call, whatever the key's setting. Someone who unsubscribed always stays unsubscribed.

consentStatement?boolean

The creator's statement „I hold these people's marketing consent and answer for it”, recorded with the consent. Required with marketingConsent: true unless the key's setting already carries it.

Response Body

`application/json`

curl -X POST "https://example.com/clients" \  -H "Content-Type: application/json" \  -d '{    "email": "string"  }'

{  "clientId": "string",  "created": true,  "createdUser": true,  "marketingConsent": "granted"}

{  "error": "string",  "message": "string"}

List client tags

GET/clients/tags

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

curl -X GET "https://example.com/clients/tags"

{  "count": 0,  "tags": [    {      "id": "string",      "name": "string",      "color": "string"    }  ]}

{  "error": "string",  "message": "string"}

Create a client tag

POST/clients/tags

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name 1-50 chars (trimmed), unique per workspace case-insensitively.

name*string

color?string|null

Response Body

`application/json`

curl -X POST "https://example.com/clients/tags" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "ok": true,  "tag": {    "id": "string",    "name": "string",    "color": "string",    "createdAt": "string"  }}

{  "error": "string",  "message": "string"}

List custom contact fields

GET/clients/custom-fields

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

curl -X GET "https://example.com/clients/custom-fields"

{  "count": 0,  "fields": [    {      "key": "string",      "name": "string",      "type": "text",      "options": [        {          "key": "string",          "label": "string",          "archived": true        }      ],      "archived": true,      "createdAt": "string"    }  ]}

{  "error": "string",  "message": "string"}

Add or remove tags on clients

POST/clients/tags/assignments

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Add / remove tag IDS on up to 200 clients; addTagIds must exist in the registry.

clientIds*array<string>

Up to MAX_BULK_TAG_CLIENTS_PER_REQUEST client ids.

addTagIds?array<string>

removeTagIds?array<string>

Response Body

`application/json`

curl -X POST "https://example.com/clients/tags/assignments" \  -H "Content-Type: application/json" \  -d '{    "clientIds": [      "string"    ]  }'

{  "ok": true,  "results": [    {      "clientId": "string",      "tags": [        "string"      ]    }  ],  "skippedClientIds": [    "string"  ]}

{  "error": "string",  "message": "string"}

Rename or recolour a client tag

PATCH/clients/tags/{tagId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

tagId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Rename and/or recolour — the tag id (and every assignment) is untouched.

name?string

color?string|null

Response Body

`application/json`

curl -X PATCH "https://example.com/clients/tags/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "ok": true,  "tag": {    "id": "string",    "name": "string",    "color": "string",    "createdAt": "string"  }}

{  "error": "string",  "message": "string"}

Delete a client tag

DELETE/clients/tags/{tagId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

tagId*string

Response Body

`application/json`

curl -X DELETE "https://example.com/clients/tags/string"

{  "ok": true,  "clientsUntagged": 0}

{  "error": "string",  "message": "string"}

Export clients as CSV

GET/clients/export

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Query Parameters

columns?string

Comma-separated optional column groups, any subset of: tags, stats, emailSubscription, activity, accesses, invoiceData, attribution, identifiers. Omit for identity columns only.

search?string

Case-insensitive prefix match on email / first name / last name.

products?string

has = only clients with active product access, no = only clients without any.

createdFrom?string

Only clients added on/after this ISO date (inclusive).

createdTo?string

Only clients added on/before this ISO date (inclusive).

limit?string

Row cap (default and max 20000).

Response Body

`application/json`

curl -X GET "https://example.com/clients/export"

{  "csv": "string",  "rowCount": 0,  "truncated": true}

{  "error": "string",  "message": "string"}

Revoke access for every client matching a filter

POST/clients/bulk-filtered-action

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

POST /clients/bulk-filtered-action — revoke (archive) access in up to 10 products for EVERY client matching the Customers-list filter; the run resolves the client set server-side.

action*string

productIds*array<string>

Products to revoke in (max 10, mirrors the list filter headroom).

clientsFilter*

The filter half of QueryClientsRequestDTO - what a filter-wide bulk action carries instead of a client list, so the run resolves the SAME set the Customers list showed (paging and sort don't change membership).

runTasks?boolean

Replay product automation tasks for each revoked client.

Response Body

`application/json`

curl -X POST "https://example.com/clients/bulk-filtered-action" \  -H "Content-Type: application/json" \  -d '{    "action": "archive",    "productIds": [      "string"    ],    "clientsFilter": {}  }'

{  "runId": "string"}

{  "error": "string",  "message": "string"}

Delete clients

POST/clients/delete

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

POST /clients/delete — up to 200 client ids per call.

clientIds*array<string>

Response Body

`application/json`

curl -X POST "https://example.com/clients/delete" \  -H "Content-Type: application/json" \  -d '{    "clientIds": [      "string"    ]  }'

{  "deletedClientIds": [    "string"  ],  "skipped": [    {      "clientId": "string",      "reason": "not-found"    }  ]}

{  "error": "string",  "message": "string"}

Client detail

GET/clients/{clientId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

clientId*string

Client id

Response Body

`application/json`

curl -X GET "https://example.com/clients/string"

{  "id": "string",  "email": "string",  "firstName": "string",  "lastName": "string",  "phoneNumber": "string",  "totalOrders": 0,  "totalSpentCents": 0,  "activeProducts": 0,  "language": "string",  "discordId": "string",  "githubId": 0,  "tagIds": [    "string"  ],  "emailSubscriptionStatus": "pending",  "attribution": {    "utmSource": "string",    "utmMedium": "string",    "utmCampaign": "string",    "utmTerm": "string",    "utmContent": "string",    "fbclid": "string",    "gclid": "string",    "metaCampaignId": "string",    "metaAdId": "string",    "metaCampaignName": "string",    "metaAdName": "string",    "capturedAt": "string"  },  "customFields": {    "property1": "string",    "property2": "string"  },  "createdAt": "string",  "previousEmails": [    "string"  ],  "firstSeen": "string",  "lastSeen": "string",  "invoiceData": {    "companyName": "string",    "nip": "string",    "street": "string",    "postalCode": "string",    "city": "string",    "country": "string"  },  "invoiceProfiles": [    {      "companyName": "string",      "nip": "string",      "street": "string",      "postalCode": "string",      "city": "string",      "country": "string"    }  ]}

{  "error": "string",  "message": "string"}

Update a client

PATCH/clients/{clientId}

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

clientId*string

Client id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Partial update of a client's profile fields. Omitted fields are left unchanged.

firstName?string

lastName?string

phoneNumber?string|null

language?string|null

customFields?

Partial update of custom field values by field key: keys left out stay as they are, null clears. Values are normalized per field type (numeric strings, YYYY-MM-DD / DD.MM.YYYY, option key or label, true / tak). All or nothing: an unknown key, an archived field or a value of the wrong type fails the request with 400 invalid-custom-fields and writes nothing.

Response Body

`application/json`

curl -X PATCH "https://example.com/clients/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "clientId": "string"}

{  "error": "string",  "message": "string"}

List a client's product accesses

GET/clients/{clientId}/product-accesses

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

clientId*string

Client id

Query Parameters

status?string

Filter on the derived access status. Omit for the complete list (all statuses).

Value in

"active"
"revoked"
"expired"

Response Body

`application/json`

curl -X GET "https://example.com/clients/string/product-accesses"

{  "items": [    {      "accessId": "string",      "productId": "string",      "productName": "string",      "productType": "course",      "status": "active",      "planId": "string",      "paymentType": "one_time",      "grantedAt": "string",      "updatedAt": "string",      "accessEndsAt": "string",      "cancelAtPeriodEnd": true,      "revokedAt": "string",      "revokeReason": "access_end",      "source": "purchase",      "orderId": "string",      "checkoutId": "string",      "isTest": true    }  ]}

{  "error": "string",  "message": "string"}

Bulk action on a product's clients

POST/products/{productId}/clients/bulk-action

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

productId*string

Product id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

POST /products/{productId}/clients/bulk-action — the product comes from the path. data is ArchiveClientsData for archive / delete and ChangeClientPeriodData for change_client_period.

action*BulkClientsApiAction

Bulk actions callable through the public API — every ProductClientAction except the product-delete fan-out, which only DeleteProductUseCase enqueues internally (it cancels live Stripe subscriptions); the route answers 400 for it.

Value in

"archive"
"change_client_period"
"delete"

data*|

Response Body

`application/json`

curl -X POST "https://example.com/products/string/clients/bulk-action" \  -H "Content-Type: application/json" \  -d '{    "action": "archive",    "data": {      "processAllClients": true,      "runTasks": true    }  }'

{  "runId": "string"}

{  "error": "string",  "message": "string"}

List a product's clients

GET/products/{productId}/clients

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

productId*string

Product id

Query Parameters

accessStatus?string

Filter on the derived access status; all returns every grant. Default: active.

Value in

"active"
"revoked"
"expired"
"all"

status?string

Legacy: stored grant status (archived = revoked + expired). Ignored when accessStatus is sent.

Value in

"active"
"archived"

limit?integer

Page size, max 100 (default 50).

cursor?string

The previous page's nextCursor.

Response Body

`application/json`

curl -X GET "https://example.com/products/string/clients"

{  "items": [    {      "accessId": "string",      "productId": "string",      "productName": "string",      "productType": "course",      "status": "active",      "planId": "string",      "paymentType": "one_time",      "grantedAt": "string",      "updatedAt": "string",      "accessEndsAt": "string",      "cancelAtPeriodEnd": true,      "revokedAt": "string",      "revokeReason": "access_end",      "source": "purchase",      "orderId": "string",      "checkoutId": "string",      "isTest": true,      "clientId": "string",      "email": "string",      "firstName": "string",      "lastName": "string",      "phoneNumber": "string",      "discordId": "string",      "priceId": "string",      "accessStartsAt": "string"    }  ],  "nextCursor": "string"}

{  "error": "string",  "message": "string"}

Grant product access

POST/products/{productId}/clients

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

productId*string

Product id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Grant a customer access to a product without a purchase (the dashboard's "New client access"). Default = free lifetime access; accessUntil makes a time-limited comp (free grants only); priceId enrolls under an existing price without billing. The welcome/sign-in email is sent only when sendWelcomeEmail is true.

email*string

firstName?string

lastName?string

priceId?string

planId?string

Plan of a multi-plan product to enroll the customer in (the product's plans[].id): bundled products and communities follow it exactly as after buying that plan. Omitted = the plan of priceId, else the default plan. A priceId selling another plan is refused (400).

accessUntil?string

ISO date the access ends (free grants only). Omit for lifetime.

sendWelcomeEmail?boolean

runPurchaseAutomations?boolean

Also run the product's purchase automations ("Nowy zakup" workflows) for this person, as if they had bought it — marked as a grant, amount 0. Default false.

payment?

The customer already paid outside Zanfia (bank transfer after a proforma, cash, ...). The grant then also records ONE paid order dated paidAt: it shows in the orders list, the sales stats and the customer's purchase history. No customer email, invoice or purchase automation comes from it.

Response Body

`application/json`

curl -X POST "https://example.com/products/string/clients" \  -H "Content-Type: application/json" \  -d '{    "email": "string"  }'

{  "granted": true,  "isFree": true}

{  "error": "string",  "message": "string"}

List a product's plan-bundled access holders

GET/products/{productId}/clients/bundled-access

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

productId*string

Product id

Response Body

`application/json`

curl -X GET "https://example.com/products/string/clients/bundled-access"

{  "items": [    {      "clientId": "string",      "email": "string",      "firstName": "string",      "lastName": "string",      "viaProductId": "string",      "viaProductName": "string",      "viaPlanName": "string",      "sinceAt": "string"    }  ]}

{  "error": "string",  "message": "string"}

Revoke product access

POST/products/{productId}/clients/revoke-access

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

productId*string

Product id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Revoke a customer's product access. NO refund is issued. Access backed by a subscription is revoked once the subscription is over in Stripe (checked live, KI#1448); a subscription that is still live is refused (409 with its status) unless cancelSubscription is set, which cancels it now and revokes in one step. Reversible via the grant route.

email*string

runAutomations?boolean

Run the product's access-end automation tasks (default false).

cancelSubscription?boolean

Cancel a still-live subscription now, then revoke (default false: a live one is refused).

silent?boolean

No e-mail, no automations and no workflows for this revoke (default false). Wins over runAutomations.

Response Body

`application/json`

curl -X POST "https://example.com/products/string/clients/revoke-access" \  -H "Content-Type: application/json" \  -d '{    "email": "string"  }'

{  "revoked": true,  "subscription": "none"}

{  "error": "string",  "message": "string"}

Change an access period

POST/products/{productId}/clients/access-period

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

productId*string

Product id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Re-window a TIME-LIMITED (one-time) access period. Provide exactly one field.

email*string

endDate?string

New absolute end, ISO date.

addDays?number

Relative: extend (negative = shorten) the current end by N days.

Response Body

`application/json`

curl -X POST "https://example.com/products/string/clients/access-period" \  -H "Content-Type: application/json" \  -d '{    "email": "string"  }'

{  "accessEndsAt": "string"}

{  "error": "string",  "message": "string"}

Cancel a client's subscription

POST/products/{productId}/clients/cancel-subscription

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

productId*string

Product id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Creator-side cancel of ONE client's live subscription to ONE product (POST /products/:productId/clients/cancel-subscription). Stops billing; access runs to the end of the paid period (or ends immediately when the latest invoice is unpaid). Idempotent: a subscription already set to cancel at period end answers 200 again; one Stripe already ended answers alreadyCancelled: true and the access record is brought in line with it.

email*string

The client's e-mail address exactly as stored on the client.

Response Body

`application/json`

curl -X POST "https://example.com/products/string/clients/cancel-subscription" \  -H "Content-Type: application/json" \  -d '{    "email": "string"  }'

{  "cancelled": true,  "alreadyCancelled": true}

{  "error": "string",  "message": "string"}

List client notes

GET/clients/{clientId}/notes

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

clientId*string

Client id

Response Body

`application/json`

curl -X GET "https://example.com/clients/string/notes"

{  "notes": [    {      "id": "string",      "text": "string",      "authorId": "string",      "authorName": "string",      "createdAt": "string"    }  ]}

{  "error": "string",  "message": "string"}

Add a client note

POST/clients/{clientId}/notes

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

clientId*string

Client id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

text*string

Up to MAX_CLIENT_NOTE_LENGTH (5000) characters.

Response Body

`application/json`

curl -X POST "https://example.com/clients/string/notes" \  -H "Content-Type: application/json" \  -d '{    "text": "string"  }'

{  "note": {    "id": "string",    "text": "string",    "authorId": "string",    "authorName": "string",    "createdAt": "string"  }}

{  "error": "string",  "message": "string"}

Client email delivery log

GET/clients/{clientId}/email-log

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

clientId*string

Client id

Query Parameters

limit?integer

Newest entries to return (default 20, max 50).

Response Body

`application/json`

curl -X GET "https://example.com/clients/string/email-log"

{  "email": "string",  "entries": [    {      "sentAt": "string",      "statusUpdatedAt": "string",      "subject": "string",      "template": "string",      "status": "submitted",      "statusDetails": "string",      "orderId": "string",      "campaignId": "string",      "automationId": "string",      "tracked": true,      "openedAt": "string",      "clickedAt": "string"    }  ]}

{  "error": "string",  "message": "string"}

Change a client's email

POST/clients/{clientId}/change-email

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

clientId*string

Client id

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

newEmail*string

sendEmailNotification?boolean

Notify the client at the NEW address (sign-in link email). Defaults to true.

Response Body

`application/json`

curl -X POST "https://example.com/clients/string/change-email" \  -H "Content-Type: application/json" \  -d '{    "newEmail": "string"  }'

{  "clientId": "string",  "grantsUpdated": 0}

{  "error": "string",  "message": "string"}

List a client's devices

GET/clients/{clientId}/devices

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

clientId*string

Client id

Response Body

`application/json`

curl -X GET "https://example.com/clients/string/devices"

{  "devices": [    {      "deviceId": "string",      "clientKind": "web",      "deviceName": "string",      "createdAt": "string",      "lastSeen": "string",      "activeUntil": "string",      "isCurrent": true    }  ]}

{  "error": "string",  "message": "string"}

Revoke a client device

POST/clients/{clientId}/devices/{deviceId}/revoke

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

clientId*string

Client id

deviceId*string

Customer device slot id

Response Body

`application/json`

curl -X POST "https://example.com/clients/string/devices/string/revoke"

{  "status": "revoked",  "deviceId": "string"}

{  "error": "string",  "message": "string"}

Reset a client's devices

POST/clients/{clientId}/devices/reset

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Path Parameters

clientId*string

Client id

Response Body

`application/json`

curl -X POST "https://example.com/clients/string/devices/reset"

{  "revokedCount": 0}

{  "error": "string",  "message": "string"}

Bulk-import contacts

POST/clients/import

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Bulk contact import — one bounded batch of contact-only client creates (no product grant, no order), the row shape a CSV maps onto naturally. Each row goes through the same create path as POST /clients (real Auth identity, dedup by email); tagIds are applied to every resolved row. Larger files are chunked by the caller (max 100 rows per request).

contacts*array<>

tagIds?array<string>

Existing tag ids from the workspace tag registry — unknown ids fail the whole request.

Response Body

`application/json`

curl -X POST "https://example.com/clients/import" \  -H "Content-Type: application/json" \  -d '{    "contacts": [      {        "email": "string"      }    ]  }'

{  "results": [    {      "email": "string",      "status": "created",      "clientId": "string",      "skippedCustomFields": [        "string"      ]    }  ],  "created": 0,  "existing": 0,  "invalid": 0,  "overLimit": 0,  "customFieldValuesSkipped": 0}

{  "error": "string",  "message": "string"}

Preview a client merge

GET/clients/merge-preview

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Response Body

`application/json`

curl -X GET "https://example.com/clients/merge-preview"

{  "preview": {    "workspaceId": "string",    "survivorWcid": "string",    "loserWcid": "string",    "survivorEmail": "string",    "loserEmail": "string",    "resultingPreviousEmails": [      "string"    ],    "money": {      "survivorTotalSpentMinor": 0,      "loserTotalSpentMinor": 0,      "sumMinor": 0,      "note": "string",      "ordersMovingCount": 0    },    "grants": [      {        "productId": "string",        "productName": "string",        "action": "move",        "reason": "string"      }    ],    "blocked": {      "reason": "active-subscription",      "subscriptions": [        {          "productId": "string",          "subscriptionId": "string",          "side": "survivor"        }      ]    },    "profileOverwrites": [      {        "field": "firstName",        "survivorValueKept": "string",        "loserValueDiscarded": "string",        "downstreamUnlink": true      }    ],    "invoiceProfiles": {      "survivorCount": 0,      "loserCount": 0,      "note": "string"    },    "community": {      "computed": true,      "communities": [        {          "communityId": "string",          "communityName": "string",          "action": "merge",          "authoredRePointCount": 0        }      ],      "communitiesTouchedCount": 0,      "authoredRePointCount": 0,      "note": "string"    },    "irreversible": true,    "previewHash": "string"  }}

{  "error": "string",  "message": "string"}

Merge duplicate clients

POST/clients/merge

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

⚠️ DESTRUCTIVE AND IRREVERSIBLE: merges the duplicate client into the survivor — grants move/dedupe, community membership and authored content re-point, profiles coalesce, and the duplicate client is TOMBSTONED. There is no undo route (recovery is an operator-level restore from the merge snapshot). Requires a fresh previewHash from GET /clients/merge-preview; execute aborts with 409 if the recomputed plan differs. A merge never touches Stripe — a live subscription on either side blocks it (409).

survivorClientId*string

The client that remains.

duplicateClientId*string

The client merged in and tombstoned.

previewHash*string

preview.previewHash from a fresh GET /clients/merge-preview.

Response Body

`application/json`

curl -X POST "https://example.com/clients/merge" \  -H "Content-Type: application/json" \  -d '{    "survivorClientId": "string",    "duplicateClientId": "string",    "previewHash": "string"  }'

{  "survivorClientId": "string",  "grantsProcessed": 0,  "merged": true}

{  "error": "string",  "message": "string"}

Bulk subscribe/unsubscribe clients (email)

POST/clients/email-subscription

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Set the marketing-email subscription of MANY clients at once (the Customers-list "Subscribe" / "Unsubscribe" bulk actions). Source manual. Subscribing requires the creator to attest the consent basis via reason; unsubscribing takes no reason. Clients already in the target status are reported as unchanged.

status*string

reason*ClientEmailSubscriptionReason

Why a creator subscribed clients by hand (the Customers-list bulk action, "Mam zgodę tych osób" in the campaign editor, and the consent question of the Klienci contact import). Recorded next to the manual / import source as the consent basis, so a later complaint can be answered with more than "set manually".

Value in

"imported-from-other-list"
"existing-customers-consent"
"asked-directly"
"other"

reasonNote?string

Optional detail for reason, trimmed, at most MAX_EMAIL_SUBSCRIPTION_REASON_NOTE_LENGTH chars.

clientIds*array<string>

Up to MAX_BULK_EMAIL_SUBSCRIPTION_CLIENTS_PER_REQUEST client ids.

Response Body

`application/json`

curl -X POST "https://example.com/clients/email-subscription" \  -H "Content-Type: application/json" \  -d '{    "status": "subscribed",    "reason": "imported-from-other-list",    "clientIds": [      "string"    ]  }'

{  "ok": true,  "updatedClientIds": [    "string"  ],  "unchangedClientIds": [    "string"  ],  "skippedClientIds": [    "string"  ]}

{  "error": "string",  "message": "string"}

Bulk subscribe/unsubscribe clients (SMS)

POST/clients/sms-subscription

Authorization

bearerAuth

AuthorizationBearer <token>

API key from Dashboard → Integrations → API, MCP and CLI.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Set the marketing-SMS consent of MANY clients at once (the Customers-list "Subscribe to SMS" / "Unsubscribe from SMS" bulk actions). Source manual. Separate from the e-mail twin on purpose: SMS is its own consent under PL/EU rules, so an e-mail opt-in is never a basis here and the reason list is narrower (ClientSmsSubscriptionReason). Subscribing requires the creator to attest the basis; unsubscribing takes no reason.

status*string

reason*ClientSmsSubscriptionReason

Why a creator subscribed clients to SMS by hand. Deliberately narrower than the email equivalent: PL/EU law treats SMS marketing as requiring its own explicit, provable consent, so "they bought something" is NOT a basis and has no entry here.

Value in

"explicit-sms-consent"
"asked-directly"
"other"

reasonNote?string

Optional detail for reason, trimmed, at most MAX_EMAIL_SUBSCRIPTION_REASON_NOTE_LENGTH chars.

clientIds*array<string>

Up to MAX_BULK_SMS_SUBSCRIPTION_CLIENTS_PER_REQUEST client ids.

Response Body

`application/json`

curl -X POST "https://example.com/clients/sms-subscription" \  -H "Content-Type: application/json" \  -d '{    "status": "subscribed",    "reason": "explicit-sms-consent",    "clientIds": [      "string"    ]  }'

{  "ok": true,  "updatedClientIds": [    "string"  ],  "unchangedClientIds": [    "string"  ],  "skippedClientIds": [    "string"  ]}

{  "error": "string",  "message": "string"}

Was this article helpful?

Spotted something off? Tell us at support@zanfia.com.

List clients

200application/json

4XXapplication/json

Add a client (contact only)

200application/json

4XXapplication/json

List client tags

200application/json

4XXapplication/json

Create a client tag

201application/json

4XXapplication/json

List custom contact fields

200application/json

4XXapplication/json

Add or remove tags on clients

200application/json

4XXapplication/json

Rename or recolour a client tag

200application/json

4XXapplication/json

Delete a client tag

200application/json

4XXapplication/json

Export clients as CSV

200application/json

4XXapplication/json

Revoke access for every client matching a filter

200application/json

4XXapplication/json

Delete clients

200application/json

4XXapplication/json

Client detail

200application/json

4XXapplication/json

Update a client

200application/json

4XXapplication/json

List a client's product accesses

200application/json

4XXapplication/json

Bulk action on a product's clients

200application/json

4XXapplication/json

List a product's clients

200application/json

4XXapplication/json

Grant product access

200application/json

4XXapplication/json

List a product's plan-bundled access holders

200application/json

4XXapplication/json

Revoke product access

200application/json

4XXapplication/json

Change an access period

200application/json

4XXapplication/json

Cancel a client's subscription

200application/json

4XXapplication/json

List client notes

200application/json

4XXapplication/json

Add a client note

200application/json

4XXapplication/json

Client email delivery log

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`