Boarding Forms API Reference

This reference covers the API endpoints for creating and managing boarding form templates and generating form links for merchants. For conceptual information, see Boarding Forms.

Form Templates

Form templates define the appearance and behavior of boarding forms. Create templates via API or Dashboard, then reference them when generating form links.

Create Form Template

Creates a new form template with branding and configuration settings.

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

This endpoint accepts multipart/form-data to support logo upload along with template configuration.

Request Fields:

Response:

{
  "id": "formTemp_1abc2def3ghi4jkl",
  "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": "2024-01-15T10:30:00Z",
  "createdBy": "usr_abc123"
}

Update Form Template

Updates an existing form template. Only provided fields are updated.

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

Path Parameters:

Request Fields: Same as Create Form Template (all optional)

📘

Template Updates

Template changes apply to new form links only. Existing form links continue using the configuration from when they were generated.

Get All Form Templates

Returns all form templates for your platform.

GET /v1/formTemplates

Query Parameters:

Response:

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

Get Form Template by ID

Returns a specific form template.

GET /v1/formTemplates/:id

Path Parameters:

Forms

Forms are individual instances created for specific merchants using a template. Each form has a unique URL that the merchant uses to complete their application.

Create Form

Generates a boarding form link for a merchant to complete.

POST /v1/forms

Request Body:

{
  "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "connectionId": "midCon_6v59stftbs837axmpahj21m8jf",
  "formTemplateId": "formTemp_1abc2def3ghi4jkl"
}

Required Fields:

Optional Overrides:

All template properties can be overridden per-form. If not specified, the value is inherited from the template.

Response:

{
  "id": "form_5mno6pqr7stu8vwx",
  "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "connectionId": "midCon_6v59stftbs837axmpahj21m8jf",
  "formUrl": "https://boarding.yourplatform.com/form_5mno6pqr7stu8vwx/AcmeCorp",
  "status": "pending",
  "expiresAt": "2024-01-17T10:30:00Z",
  "heading": { ... },
  "button": { ... },
  "support": { ... }
}

The formUrl is the link to send to the merchant. When the merchant completes and submits the form, they're redirected to the template's returnUrl.

📘

Connection ID

You can provide either the connection ID (midCon_...) or the processor name (e.g., Payrix). If using a processor name, Preczn resolves it to the appropriate connection for that merchant.

Get Merchant Forms

Returns all forms generated for a specific merchant.

GET /v1/forms/merchant/:merchantId

Path Parameters:

Query Parameters:

Response:

{
  "forms": [
    {
      "id": "form_5mno6pqr7stu8vwx",
      "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
      "connectionId": "midCon_6v59stftbs837axmpahj21m8jf",
      "formUrl": "https://boarding.yourplatform.com/form_5mno6pqr7stu8vwx/AcmeCorp",
      "status": "completed",
      "createdOn": "2024-01-15T10:30:00Z"
    }
  ],
  "hasMore": false,
  "lastId": null
}

Get Form by ID

Returns details for a specific form.

GET /v1/forms/:formId

Path Parameters:

Form Status

Forms have the following statuses:

Related Webhooks

When autoTransmitMerchantData is enabled and the form triggers onboarding, you'll receive a merchant.updated webhook with the updated connection status.

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

📘

Tracking Form Completion

To check form completion status, query the forms API: GET /v1/forms/merchant/:merchantId. There is no dedicated webhook for form completion events.

Error Responses

Example Error:

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

Related Pages

• Boarding Forms - Overview and when to use boarding forms
• Creating Forms - Step-by-step guide to generating form links
• Boarding Form Templates - Template configuration and inheritance
• Configuring Domain Names - DNS and SSL setup
• Merchant Onboarding - Complete onboarding journey