POST/v1/integrations/apps/{appKey}/installations

Install an integration

Validates the configuration against the app, creates a dedicated live API key (scoped to Postflows, items, templates and prices) and, when a writeback is configured, a dedicated webhook endpoint for item events; both secrets are returned once. Credentials are stored sealed.

Scope integrations.manage

Path parameters

appKeystringrequired

Body

namestringmin length 2max length 120

configobjectrequired

credentialsobject

1 fields

clientSecretstringmin length 3max length 500

Returns

3 fields of the 201 answer

installationobjectrequired

13 fields

idstringrequired

appKeystringrequired

namestringrequired

configobjectrequired

5 fields

instanceUrlstringrequired

writebackMethodenumrequired

NONECONNECTED_APPSITE_GUEST

writebackUrlstring

clientIdstring

mirrorAllItemsbooleanrequired

hasCredentialsbooleanrequired

statusenumrequired

PENDINGACTIVEERRORDISABLED

lastErrorstring or nullrequired

apiKeyIdstring or nullrequired

webhookEndpointIdstring or nullrequired

lastActivityAtdate-time or nullrequired

healthCheckedAtdate-time or nullrequired

createdAtdate-timerequired

updatedAtdate-timerequired

apiKeyobjectrequired

3 fields

idstringrequired

prefixstringrequired

secretstringrequired

webhookobject or nullrequired

3 fields

idstringrequired

urlstringrequired

secretstringrequired

Responses

201Success

401Authentication required or API key invalid

403Permission or scope missing, organisation suspended

404Not found

422Validation failed

429Rate limited for this API key and class; wait Retry-After seconds

otherError (RFC 9457 problem details)

curl -X POST https://api.postbuddy.nl/v1/integrations/apps/obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K/installations \ -H "Authorization: Bearer $POSTBUDDY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Welcome card", "config": {} }'

import { PostBuddyClient } from '@postbuddy/sdk'; const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! }); const result = await client.integrations.install('obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K', { body: { name: 'Welcome card', config: {}, }, });

import os from postbuddy import Client client = Client(os.environ["POSTBUDDY_API_KEY"]) result = client.integrations.install("obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K", { "name": "Welcome card", "config": {}, })

{ "installation": { "id": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "appKey": "Example", "name": "Welcome card", "config": { "instanceUrl": "https://example.com/r/Fq3ZtR8w", "writebackMethod": "NONE", "writebackUrl": "https://example.com/r/Fq3ZtR8w", "clientId": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "mirrorAllItems": false }, "hasCredentials": false, "status": "ACTIVE", "lastError": "Example", "apiKeyId": "key_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "webhookEndpointId": "wh_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "lastActivityAt": "2026-10-16T09:14:02.000Z", "healthCheckedAt": "2026-10-16T09:14:02.000Z", "createdAt": "2026-10-16T09:14:02.000Z", "updatedAt": "2026-10-16T09:14:02.000Z" }, "apiKey": { "id": "key_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "prefix": "pb_live_3kx9", "secret": "whsec_9c1f2b7e4d" }, "webhook": { "id": "wh_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "url": "https://example.com/hooks/postbuddy", "secret": "whsec_9c1f2b7e4d" } }

{ "type": "https://docs.postbuddy.nl/errors/validation_failed", "title": "Validation failed", "status": 422, "code": "validation_failed", "detail": "Validation failed", "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "errors": [ { "field": "recipient.postalCode", "code": "invalid_string", "message": "Invalid postal code" } ] }