> ## Documentation Index > Fetch the complete documentation index at: https://help.commbox.io/llms.txt > Use this file to discover all available pages before exploring further. # Create Predefined Form Link > This API generates a personalized form link by overlaying fillable form fields onto a custom PDF or image background. This endpoint creates a unique form URL that can be sent to customers for completion. ### How It Works 1. Upload a background document (PDF or image) 2. Specify the form template to use (via Form ID) 3. Identify the recipient (email or phone number) 4. Receive a unique form link to share with the customer ### Key Features - **Custom Branding**: Use your own PDF or image as the form background - **Field Placement**: Form fields are automatically embedded on the last page of the background document - **Conversation Linking**: Optionally link the form to an existing conversation for tracking - **Multi-Channel**: Send form links via email or SMS ## Request Parameters ### Path Parameters - `FORM_ID` **(required)**: The unique identifier of the form template (visible in the forms list screen) ### Body Parameters (multipart/form-data) - `streamProviderId` **(required)**: Customer's phone number or email address - `streamProviderType` **(required)**: Delivery method - `4` for email, `5` for phone/SMS - `referringObjectId` *(optional)*: Conversation ID to link with the generated form object for tracking purposes - `file` **(required)**: Background document file (PDF or image format) ## Important Notes **Field Positioning**: All fillable fields will appear on the **last page** of your background document **Form Object Creation**: When a recipient opens the form link, a new form object is automatically created in the system **Conversation Tracking**: Use `referringObjectId` to maintain context between the form and the originating conversation ## OpenAPI ````json POST /forms/createpredefinedlink/{FORM_ID} { "openapi": "3.0.3", "info": { "title": "CommBox API", "x-logo": { "url": "https://www.commbox.io/logo/commbox_logo_large.png" }, "version": "2.07", "termsOfService": "https://www.commbox.io/end-user-license-agreement-eula/", "contact": { "name": "commbox", "url": "https://www.commbox.io", "email": "contactus@commbox.io" } }, "servers": [ { "url": "https://api.commbox.io/", "description": "Production server" } ], "paths": { "/forms/createpredefinedlink/{FORM_ID}": { "post": { "tags": [ "Forms" ], "summary": "Create Predefined Form Link", "description": "This API generates a personalized form link by overlaying fillable form fields onto a custom PDF or image background. This endpoint creates a unique form URL that can be sent to customers for completion.\n\n### How It Works\n\n1. Upload a background document (PDF or image)\n2. Specify the form template to use (via Form ID)\n3. Identify the recipient (email or phone number)\n4. Receive a unique form link to share with the customer\n\n### Key Features\n\n- **Custom Branding**: Use your own PDF or image as the form background\n- **Field Placement**: Form fields are automatically embedded on the last page of the background document\n- **Conversation Linking**: Optionally link the form to an existing conversation for tracking\n- **Multi-Channel**: Send form links via email or SMS\n\n## Request Parameters\n\n### Path Parameters\n- `FORM_ID` **(required)**: The unique identifier of the form template (visible in the forms list screen)\n\n### Body Parameters (multipart/form-data)\n- `streamProviderId` **(required)**: Customer's phone number or email address\n- `streamProviderType` **(required)**: Delivery method - `4` for email, `5` for phone/SMS\n- `referringObjectId` *(optional)*: Conversation ID to link with the generated form object for tracking purposes\n- `file` **(required)**: Background document file (PDF or image format)\n\n## Important Notes\n\n **Field Positioning**: All fillable fields will appear on the **last page** of your background document\n\n **Form Object Creation**: When a recipient opens the form link, a new form object is automatically created in the system\n\n **Conversation Tracking**: Use `referringObjectId` to maintain context between the form and the originating conversation", "operationId": "Create_Predefined_Form_Link", "parameters": [ { "name": "FORM_ID", "in": "path", "description": "Form Id - Form number (as seen on the forms list screen)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "streamProviderId", "streamProviderType" ], "properties": { "streamProviderId": { "type": "string", "description": "The identifier of the receiving customer by their phone number or email", "example": "19175552345" }, "streamProviderType": { "type": "string", "enum": [ "4", "5" ], "description": "4 for email, 5 for phone number", "example": "5" }, "referringObjectId": { "type": "integer", "description": "(optional) The object ID of the conversation related to the Form", "example": 312345 }, "file": { "type": "string", "format": "binary", "description": "Background document file (PDF or image format). Upload the file to the Value section" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 200 }, "description": { "type": "string", "example": "Operation successful" }, "response_time": { "type": "string", "format": "date-time", "example": "2025-02-06T07:51:52.2581942Z" }, "data": { "type": "object", "properties": { "conversation_id": { "type": "string", "description": "The ID of the conversation linked to this form", "example": "312345" }, "form_link": { "type": "string", "format": "uri", "description": "The unique URL for the generated form", "example": "https://apps.commbox.io/form/commbox/499fdc93aa804a4b8266251224944d6a" } }, "required": [ "form_link" ] } }, "required": [ "status", "description", "response_time", "data" ] } } } }, "400": { "description": "Bad Request - The request could not be understood by the server. Incoming parameters might not be valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 400 }, "description": { "type": "string", "example": "Bad Request" }, "response_time": { "type": "string", "format": "date-time", "example": "2025-02-06T07:51:52.2581942Z" } } } } } }, "401": { "description": "Unauthorized - The supplied credentials, if any, are not sufficient to access the resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 401 }, "description": { "type": "string", "example": "Unauthorized" }, "response_time": { "type": "string", "format": "date-time", "example": "2025-02-06T07:51:52.2581942Z" } } } } } }, "404": { "description": "Not found - The requested resource is not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 404 }, "description": { "type": "string", "example": "Not Found" }, "response_time": { "type": "string", "format": "date-time", "example": "2025-02-06T07:51:52.2581942Z" } } } } } }, "429": { "description": "Too Many Requests - Too many requests have been made in a short period of time (Throttling)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 429 }, "description": { "type": "string", "example": "Too Many Requests" }, "response_time": { "type": "string", "format": "date-time", "example": "2025-02-06T07:51:52.2581942Z" } } } } } }, "500": { "description": "Server Error - The server could not return the representation due to an internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 500 }, "description": { "type": "string", "example": "Internal Server Error" }, "response_time": { "type": "string", "format": "date-time", "example": "2025-02-06T07:51:52.2581942Z" } } } } } } } } } } } ````