Integrations

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

10 min readLast updated Sep 22, 2026

The credential-bearing connections behind Settings → Integrations, under the dedicated integrations:read / integrations:write scopes (a products key deliberately cannot plant a gateway or swap your ESP): email-marketing accounts (ActiveCampaign, Kit, MailerLite, MailChimp, GetResponse, Pipedrive — connect, disconnect, refresh lists), manual Meta pixel + Conversions API entries, and the manual (wire-transfer) payment method. Keys and tokens are verified against the provider before anything is stored, go to Secret Manager, and are never returned. OAuth-based providers (Stripe Connect, Meta OAuth, Google, social networks) and the credential payment gateways stay dashboard-only for now; the pixel integrations (GA4, GTM, TikTok, X, LinkedIn, Clarity, Hotjar) live under Conversion tracking. All routes require a Authorization: Bearer header — see Authentication.

Integrations overview

GET/integrations

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/integrations"

{  "emailClients": [    {      "client": "ActiveCampaign",      "url": "string",      "name": "string",      "listsCount": 0,      "tagsCount": 0,      "serverPrefix": "string",      "createdAt": "string",      "updatedAt": "string"    }  ],  "metaConversionApi": [    {      "id": "string",      "name": "string",      "pixelId": "string",      "serverSide": true,      "disabled": true,      "isWorkspaceDefault": true,      "trackPurchase": true,      "trackInitCheckout": true,      "trackAddToCart": true,      "trackTrialStarted": true,      "createdAt": "string",      "updatedAt": "string"    }  ],  "conversionTrackingIntegrationsCount": 0,  "invoicesClients": [    {      "client": "fakturownia",      "id": "string",      "url": "string",      "createdAt": "string"    }  ],  "payments": {    "stripe": true,    "payU": true,    "tpay": true,    "payNow": true,    "przelewy24": true,    "paypal": true,    "dodo": true,    "manual": {      "name": "string",      "instructions": "string",      "updatedAt": "string"    }  },  "sms": {    "defaultProvider": "twilio",    "twilio": {      "accountSid": "string",      "region": "us1",      "senderKind": "messagingService",      "sender": "string",      "senderLabel": "string"    },    "smsapi": {      "region": "pl",      "sender": "string",      "senders": [        "string"      ],      "accountName": "string",      "needsReconnect": true    }  }}

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

Connect an email client

POST/integrations/email-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.

POST /integrations/email-clients — discriminated by client; the key is verified against the provider first.

client*string

url*string

apiKey*string

Response Body

`application/json`

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

{  "client": "ActiveCampaign",  "url": "string",  "name": "string",  "listsCount": 0,  "tagsCount": 0,  "serverPrefix": "string",  "createdAt": "string",  "updatedAt": "string"}

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

Disconnect an email client

POST/integrations/email-clients/disconnect

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 /integrations/email-clients/disconnect — 409 account-in-use lists the products still using it.

client*EmailClient

Value in

"ActiveCampaign"
"MailChimp"
"ConvertKit"
"MailerLite"
"GetResponse"
"FreshMail"
"Pipedrive"

url*string

The account identifier shown in the UI — mailer accounts are keyed by url.

Response Body

`application/json`

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

{  "status": "ok"}

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

Refresh an email client's lists

POST/integrations/email-clients/refresh-lists

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 /integrations/email-clients/refresh-lists — re-fetches lists + tags with the stored key.

client*string

Value in

"ActiveCampaign"
"MailChimp"
"ConvertKit"
"MailerLite"
"GetResponse"

url*string

serverPrefix?string

MailChimp only.

Response Body

`application/json`

curl -X POST "https://example.com/integrations/email-clients/refresh-lists" \  -H "Content-Type: application/json" \  -d '{    "client": "ActiveCampaign",    "url": "string"  }'

{  "client": "ActiveCampaign",  "url": "string",  "name": "string",  "listsCount": 0,  "tagsCount": 0,  "serverPrefix": "string",  "createdAt": "string",  "updatedAt": "string"}

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

Add or edit a Meta pixel / Conversions API entry

PUT/integrations/meta-conversion-api

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.

PUT /integrations/meta-conversion-api — create (no id) or edit (with id) a manual Meta pixel + Conversions API entry. accessToken is validated against Meta before saving; omitted on edit = keep the stored token.

id?|

Present when editing an existing entry.

accessToken?|

Null on edit when only the pixel id / toggles change — stored token is revalidated.

pixelId*string

name*string

trackInitCheckout*boolean

trackAddToCart*boolean

trackPurchase*boolean

trackTrialStarted?boolean

Response Body

`application/json`

curl -X PUT "https://example.com/integrations/meta-conversion-api" \  -H "Content-Type: application/json" \  -d '{    "pixelId": "string",    "name": "string",    "trackInitCheckout": true,    "trackAddToCart": true,    "trackPurchase": true  }'

{  "id": "string",  "name": "string",  "pixelId": "string",  "serverSide": true,  "disabled": true,  "isWorkspaceDefault": true,  "trackPurchase": true,  "trackInitCheckout": true,  "trackAddToCart": true,  "trackTrialStarted": true,  "createdAt": "string",  "updatedAt": "string"}

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

Remove a Meta pixel / Conversions API entry

DELETE/integrations/meta-conversion-api/{integrationId}

Authorization

bearerAuth

AuthorizationBearer <token>

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

In: header

Path Parameters

integrationId*string

Response Body

`application/json`

curl -X DELETE "https://example.com/integrations/meta-conversion-api/string"

{  "status": "ok"}

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

Configure the manual payment method

PUT/integrations/payments/manual

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.

PUT /integrations/payments/manual — configure the wire-transfer payment method.

name*string

instructions*string

Plain multiline text shown to buyers on the thank-you page and in the order email.

Response Body

`application/json`

curl -X PUT "https://example.com/integrations/payments/manual" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "instructions": "string"  }'

{  "name": "string",  "instructions": "string",  "updatedAt": "string"}

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

Remove the manual payment method

DELETE/integrations/payments/manual

Authorization

bearerAuth

AuthorizationBearer <token>

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

In: header

Response Body

`application/json`

curl -X DELETE "https://example.com/integrations/payments/manual"

{  "status": "ok"}

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

Connect an invoicing account

POST/integrations/invoices-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.

POST /integrations/invoices-clients — discriminated by client; id present = edit.

client*string

id?string

url*string

apiKey*string

accountName*string

departmentId?string|null

settings?||null

Response Body

`application/json`

curl -X POST "https://example.com/integrations/invoices-clients" \  -H "Content-Type: application/json" \  -d '{    "client": "fakturownia",    "url": "string",    "apiKey": "string",    "accountName": "string"  }'

{  "client": "fakturownia",  "id": "string",  "url": "string",  "createdAt": "string"}

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

Disconnect an invoicing account

POST/integrations/invoices-clients/disconnect

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 /integrations/invoices-clients/disconnect — client + entry id.

client*InvoicesClient

Value in

"fakturownia"
"ifirma"
"wfirma"
"inFakt"
"wFirmaV2"
"ingKsiegowosc"
"stripe"

id*string

The account entry id (uuid).

Response Body

`application/json`

curl -X POST "https://example.com/integrations/invoices-clients/disconnect" \  -H "Content-Type: application/json" \  -d '{    "client": "fakturownia",    "id": "string"  }'

{  "status": "ok"}

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

Connect a payment gateway

POST/integrations/payments/gateways

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 /integrations/payments/gateways — discriminated by gateway; credentials are verified against the gateway first.

name*string

posId*string

clientId*string

clientSecret*string

clientSecondKey*string

gateway*string

Response Body

`application/json`

curl -X POST "https://example.com/integrations/payments/gateways" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "posId": "string",    "clientId": "string",    "clientSecret": "string",    "clientSecondKey": "string",    "gateway": "payu"  }'

{  "stripe": true,  "payU": true,  "tpay": true,  "payNow": true,  "przelewy24": true,  "paypal": true,  "dodo": true,  "manual": {    "name": "string",    "instructions": "string",    "updatedAt": "string"  }}

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

Disconnect a payment gateway

POST/integrations/payments/gateways/disconnect

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 /integrations/payments/gateways/disconnect.

gateway*|||||

The credential payment gateways connectable over the API (Stripe is OAuth, manual has its own route).

Response Body

`application/json`

curl -X POST "https://example.com/integrations/payments/gateways/disconnect" \  -H "Content-Type: application/json" \  -d '{    "gateway": "payu"  }'

{  "stripe": true,  "payU": true,  "tpay": true,  "payNow": true,  "przelewy24": true,  "paypal": true,  "dodo": true,  "manual": {    "name": "string",    "instructions": "string",    "updatedAt": "string"  }}

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

Toggle Tpay recurring BLIK

PUT/integrations/payments/tpay/recurring-blik

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.

PUT /integrations/payments/tpay/recurring-blik.

enabled*boolean

Response Body

`application/json`

curl -X PUT "https://example.com/integrations/payments/tpay/recurring-blik" \  -H "Content-Type: application/json" \  -d '{    "enabled": true  }'

{  "status": "ok"}

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

Connect Twilio

PUT/integrations/sms/twilio

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.

PUT /integrations/sms/twilio — the auth token / API key secret is verified against Twilio first.

accountSid*string

region?TwilioRegion

Omitted = us1.

Value in

"us1"
"ie1"
"au1"

authKind?TwilioAuthKind

Omitted = authToken.

Value in

"authToken"
"apiKey"

apiKeySid?|

Required with authKind = apiKey: the public SK… key SID.

authToken*string

The account Auth Token, or the API Key secret when authKind = apiKey. Write-only: it goes straight to Secret Manager and is never returned by any read endpoint.

senderKind*TwilioSenderKind

How a Twilio connection addresses the sender. Twilio accepts either a Messaging Service (a pool with sender selection, opt-out handling and per-country sender rules configured Twilio-side) or a single concrete sender. A Messaging Service is what Twilio itself recommends for anything bulk, so it is the default the connect UI steers to.

Value in

"messagingService"
"phoneNumber"
"alphanumericSenderId"

sender*string

Messaging Service sid, an owned E.164 number, or an alphanumeric id.

Response Body

`application/json`

curl -X PUT "https://example.com/integrations/sms/twilio" \  -H "Content-Type: application/json" \  -d '{    "accountSid": "string",    "authToken": "string",    "senderKind": "messagingService",    "sender": "string"  }'

{  "accountSid": "string",  "region": "us1",  "authKind": "authToken",  "accountName": "string",  "senderKind": "messagingService",  "sender": "string",  "senderLabel": "string"}

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

Disconnect Twilio

DELETE/integrations/sms/twilio

Authorization

bearerAuth

AuthorizationBearer <token>

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

In: header

Response Body

`application/json`

curl -X DELETE "https://example.com/integrations/sms/twilio"

{  "status": "ok"}

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

Connect SMSAPI

PUT/integrations/sms/smsapi

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.

PUT /integrations/sms/smsapi — the token is verified against SMSAPI first.

region*SmsApiRegion

SMSAPI runs two separate platforms with separate accounts and tokens: the Polish one (api.smsapi.pl) and the international one (api.smsapi.com). A token from one is rejected by the other, so the connection records which platform issued it.

Value in

"pl"
"com"

apiToken*string

SMSAPI OAuth API token (Panel → Ustawienia → Tokeny API). Write-only: straight to Secret Manager, never returned by any read endpoint.

sender*string

Registered sender name, verified against the account before storing.

Response Body

`application/json`

curl -X PUT "https://example.com/integrations/sms/smsapi" \  -H "Content-Type: application/json" \  -d '{    "region": "pl",    "apiToken": "string",    "sender": "string"  }'

{  "region": "pl",  "accountName": "string",  "sender": "string",  "points": 0}

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

Disconnect SMSAPI

DELETE/integrations/sms/smsapi

Authorization

bearerAuth

AuthorizationBearer <token>

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

In: header

Response Body

`application/json`

curl -X DELETE "https://example.com/integrations/sms/smsapi"

{  "status": "ok"}

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

Refresh SMSAPI senders

POST/integrations/sms/smsapi/refresh-senders

Authorization

bearerAuth

AuthorizationBearer <token>

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

In: header

Response Body

`application/json`

curl -X POST "https://example.com/integrations/sms/smsapi/refresh-senders"

{  "senders": [    "string"  ],  "sender": "string"}

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

Set the default SMSAPI sender

PUT/integrations/sms/smsapi/default-sender

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.

sender*string

Must be one of the connection's senders.

Response Body

`application/json`

curl -X PUT "https://example.com/integrations/sms/smsapi/default-sender" \  -H "Content-Type: application/json" \  -d '{    "sender": "string"  }'

{  "senders": [    "string"  ],  "sender": "string"}

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

Set the default SMS provider

PUT/integrations/sms/default-provider

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.

Picks which connected provider workflows (and any send without an explicit pick) go through. Only a provider that is connected qualifies.

provider*SmsProvider

SMS providers a workspace can connect. Keys of integrations.sms. A workspace may hold several connections at once (BP 2026-09-17); the one in sms.defaultProvider is what workflows and anything without an explicit pick send through, and an SMS campaign may switch per campaign.

Value in

"twilio"
"smsapi"

Response Body

`application/json`

curl -X PUT "https://example.com/integrations/sms/default-provider" \  -H "Content-Type: application/json" \  -d '{    "provider": "twilio"  }'

{  "defaultProvider": "twilio"}

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

Was this article helpful?

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

Integrations overview

200application/json

4XXapplication/json

Connect an email client

200application/json

4XXapplication/json

Disconnect an email client

200application/json

4XXapplication/json

Refresh an email client's lists

200application/json

4XXapplication/json

Add or edit a Meta pixel / Conversions API entry

200application/json

4XXapplication/json

Remove a Meta pixel / Conversions API entry

200application/json

4XXapplication/json

Configure the manual payment method

200application/json

4XXapplication/json

Remove the manual payment method

200application/json

4XXapplication/json

Connect an invoicing account

200application/json

4XXapplication/json

Disconnect an invoicing account

200application/json

4XXapplication/json

Connect a payment gateway

200application/json

4XXapplication/json

Disconnect a payment gateway

200application/json

4XXapplication/json

Toggle Tpay recurring BLIK

200application/json

4XXapplication/json

Connect Twilio

200application/json

4XXapplication/json

Disconnect Twilio

200application/json

4XXapplication/json

Connect SMSAPI

200application/json

4XXapplication/json

Disconnect SMSAPI

200application/json

4XXapplication/json

Refresh SMSAPI senders

200application/json

4XXapplication/json

Set the default SMSAPI sender

200application/json

4XXapplication/json

Set the default SMS provider

200application/json

4XXapplication/json

Related articles

API overview

Authentication and API keys

`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`