Integrations - osforms

These endpoints require your login session: the ff_token cookie, or the same JWT sent as Authorization: Bearer <token>. Integrations belong to a form, and each form has at most one integration of each type. Integration configs are encrypted at rest with AES-256-GCM. Secrets (apiKey, webhook secret, Google refreshToken) are masked as •••••••• whenever a config is returned.

List a form’s integrations

GET /api/v1/integrations?formId={formId}

{
  "integrations": [
    {
      "_id": "64f1a2b3c4d5e6f7a8b9c0d1",
      "type": "EMAIL",
      "name": "Email notifications",
      "enabled": true,
      "createdAt": "2026-09-01T00:00:00.000Z",
      "updatedAt": "2026-09-01T00:00:00.000Z"
    }
  ]
}

Create an integration

POST /api/v1/integrations

{
  "formId": "671fa2b3c4d5e6f7a8b9c0aa",
  "type": "EMAIL",
  "name": "Email notifications",
  "config": {
    "provider": "resend",
    "apiKey": "re_xxxxxxxxxxxx",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "New Form Submission"
  }
}

Types: EMAIL, WEBHOOK, GOOGLE_SHEETS. Posting a type the form already has replaces that integration’s config. Returns 201 with { "integration": { "id", "type", "name", "enabled", "createdAt" } }.

EMAIL config

Field	Required	Description
`provider`	Yes	`"resend"`. (`sendgrid` and `smtp` are accepted but not implemented yet)
`apiKey`	Yes	Resend API key (`re_...`)
`from`	Yes	Sender address on your verified Resend domain
`to`	Yes	Array of recipient addresses, at least one
`subject`	No	Default `"New Form Submission"`. The form name is appended: `"{subject} - {form name}"`
`autoReply`	No	Confirmation email to the person who submitted. See Resend

WEBHOOK config

Field	Required	Description
`url`	Yes	Endpoint URL
`method`	No	`POST` (default), `PUT`, or `PATCH`
`headers`	No	Extra request headers, e.g. `{ "Authorization": "Bearer ..." }`
`secret`	No	Your signing secret. When set, requests carry an `X-osforms-Signature` header

GOOGLE_SHEETS config

Google Sheets is connected through Google OAuth from the form’s Integrations tab, not with this endpoint. See Google Sheets.

Get an integration

GET /api/v1/integrations/{id}

Returns { "integration": { "_id", "type", "name", "enabled", "config", "createdAt", "updatedAt" } } with secrets masked.

Update an integration

PATCH /api/v1/integrations/{id}

{
  "enabled": false
}

Updatable fields: name, enabled, config. config replaces the stored config, so send the complete object. To keep an existing webhook secret without resending it, pass "secret": "__KEEP_EXISTING__".

Delete an integration

DELETE /api/v1/integrations/{id}

Returns { "success": true }.

Test an integration

POST /api/v1/integrations/{id}/test

Runs the integration once with sample data (Test User, [email protected], and a few more fields). No submission is created.

{
  "success": true,
  "message": "Email sent via Resend"
}

If the integration fails, you get 400 with { "error": "Test failed", "message": "<provider error>" }.

Integration status

GET /api/v1/integrations/{id}/status

Returns type, name, and enabled. For Google Sheets it also returns connectedEmail, spreadsheetId, spreadsheetUrl, and sheetName. Per-submission success or failure is in the integration logs.

​List a form’s integrations

​Create an integration

​EMAIL config

​WEBHOOK config

​GOOGLE_SHEETS config

​Get an integration

​Update an integration

​Delete an integration

​Test an integration

​Integration status