Boarding Forms API Reference

This page documents the API endpoints for creating and managing boarding form templates and the boarding forms generated from them. For a workflow-oriented walkthrough, see Creating Forms. For onboarding a merchant to multiple fintech connections from a single form, see Multi-Connection Boarding Forms.

Form Templates

Create Form Template

Endpoint: POST /v1/formTemplates Content-Type: multipart/form-data

Creates a new form template with branding and configuration settings.

Request Fields:

Response Example:

{
  "id": "formTemp_test_7ffxgaw71x82zsg0psxd7q73nh",
  "name": "Standard Onboarding",
  "domain": "https://boarding.yourplatform.com",
  "returnUrl": "https://yourplatform.com/onboarding/complete",
  "expirationUrl": "https://yourplatform.com/onboarding/expired",
  "expirationInHours": 48,
  "displayTos": true,
  "tosUrl": "https://yourplatform.com/terms",
  "autoTransmitMerchantData": true,
  "type": "KYC",
  "heading": {
    "title": "Your Platform Name",
    "titleColor": "#000000",
    "accentColor": "#4013BE",
    "logo": "https://..."
  },
  "button": {
    "textColor": "#FFFFFF",
    "accentColor": "#808080"
  },
  "support": {
    "url": "https://yourplatform.com/support",
    "email": "[email protected]",
    "phone": "18005551234",
    "text": "Available Monday-Friday"
  },
  "isTestMode": false,
  "createdOn": "2026-05-01T10:30:00Z",
  "createdBy": "usr_abc123"
}

Update Form Template

Endpoint: PATCH /v1/formTemplates/:id Content-Type: multipart/form-data

Updates an existing form template. Only the fields included in the request are updated.

Path Parameters:

Request Fields: Same as Create Form Template — all fields are optional on update.

📘

Template changes apply to new form links only

Existing form links continue using the configuration that was in place when they were generated. Update the template, then generate new form links to apply the changes.

Get All Form Templates

Endpoint: GET /v1/formTemplates

Returns all form templates for your platform.

Query Parameters:

Response Example:

{
  "formTemplates": [
    {
      "id": "formTemp_test_7ffxgaw71x82zsg0psxd7q73nh",
      "name": "Standard Onboarding",
      "domain": "https://boarding.yourplatform.com",
      "type": "KYC",
      "isTestMode": false
    }
  ],
  "hasMore": false,
  "lastId": null
}

Get Form Template by ID

Endpoint: GET /v1/formTemplates/:id

Returns a specific form template.

Path Parameters:

Forms

Create Form

Endpoint: POST /v1/forms

Generates a boarding form link for a merchant to complete. A form can target a single fintech connection (connectionId) or multiple connections at once (connectionIds).

Request Body — Single Connection:

{
  "merchantId": "mid_1sxmscs49g95t8y6n79nt922xr",
  "connectionId": "Payrix",
  "formTemplateId": "formTemp_test_7ffxgaw71x82zsg0psxd7q73nh"
}

Request Body — Multi-Connection:

{
  "merchantId": "mid_1sxmscs49g95t8y6n79nt922xr",
  "connectionIds": ["Payrix", "Greensky"],
  "formTemplateId": "formTemp_test_7ffxgaw71x82zsg0psxd7q73nh"
}

Required Fields:

📘

Connection names vs. connection IDs

For both connectionId and entries in connectionIds, you can provide either the connection name (Payrix, Greensky, AdyenForPlatforms, etc.) or the connection ID (midCon_...). We recommend using connection names — they're easier to read, easier to copy from a list of supported connections, and don't require you to look up the connection ID for the specific merchant first. Preczn resolves connection names to the matching connection on the merchant.

📘

Pass connectionId or connectionIds, not both

A request must include exactly one of the two fields. Sending both, or neither, returns 400 Bad Request. Multi-connection forms are KYC only — combining connectionIds with type: "RFI" is rejected with a 400 Bad Request. See Multi-Connection Boarding Forms for the full feature guide.

Optional Overrides:

Any field on the form template can be overridden per form by including it in the request body.

Response Example — Single Connection:

{
  "id": "form_5mno6pqr7stu8vwx",
  "merchantId": "mid_1sxmscs49g95t8y6n79nt922xr",
  "connectionId": "midCon_6v59stftbs837axmpahj21m8jf",
  "processorName": "Payrix",
  "url": "https://boarding.yourplatform.com/form_5mno6pqr7stu8vwx/AcmeCorp",
  "expiresOn": "2026-05-07T10:30:00Z",
  "heading": { },
  "button": { },
  "support": { }
}

Response Example — Multi-Connection:

{
  "id": "form_5mno6pqr7stu8vwx",
  "merchantId": "mid_1sxmscs49g95t8y6n79nt922xr",
  "connectionIds": [
    "midCon_6v59stftbs837axmpahj21m8jf",
    "midCon_8xq2hbgptn5193cymopdq2x4kc"
  ],
  "processorNames": ["Payrix", "Greensky"],
  "url": "https://boarding.yourplatform.com/form_5mno6pqr7stu8vwx/AcmeCorp",
  "expiresOn": "2026-05-07T10:30:00Z",
  "heading": { },
  "button": { },
  "support": { }
}

Single-connection responses return connectionId and processorName (singular). Multi-connection responses return connectionIds and processorNames (plural). The two shapes are mutually exclusive — a response will never contain both.

You send the url to the merchant the same way you would for any other boarding form.

Get Merchant Forms

Endpoint: GET /v1/forms/merchant/:merchantId

Returns all forms generated for a specific merchant.

Path Parameters:

Query Parameters:

Response Example:

{
  "forms": [
    {
      "id": "form_5mno6pqr7stu8vwx",
      "merchantId": "mid_1sxmscs49g95t8y6n79nt922xr",
      "connectionId": "midCon_6v59stftbs837axmpahj21m8jf",
      "processorName": "Payrix",
      "url": "https://boarding.yourplatform.com/form_5mno6pqr7stu8vwx/AcmeCorp",
      "expiresOn": "2026-05-07T10:30:00Z",
      "createdOn": "2026-05-01T10:30:00Z"
    }
  ],
  "hasMore": false,
  "lastId": null
}

Multi-connection forms in this response use the plural connectionIds and processorNames fields in place of connectionId and processorName.

Get Form by ID

Endpoint: GET /v1/forms/:formId

Returns details for a specific form.

Path Parameters:

The response shape matches the Create Form response — single-connection forms return singular fields, multi-connection forms return plural fields.

Related Webhooks

When autoTransmitMerchantData is enabled and a submitted form triggers onboarding, you'll receive a merchant.updated webhook with the updated connection status. For multi-connection forms, you'll receive one merchant.updated event per connection as each one moves through the boarding lifecycle.

Webhook Example:

{
  "event": "merchant.updated",
  "data": {
    "id": "mid_1sxmscs49g95t8y6n79nt922xr",
    "connections": [
      {
        "id": "midCon_6v59stftbs837axmpahj21m8jf",
        "processor": "Payrix",
        "status": "Queued"
      }
    ]
  }
}

📘

No dedicated webhook fires when a form is submitted

To detect form completion, query GET /v1/forms/:formId and check the completionDate field, or subscribe to the connection-status webhooks above that fire when each connection moves through the boarding lifecycle.

Error Responses

Example Error:

{
  "statusCode": 404,
  "message": "Form Template not found",
  "error": "Not Found"
}