> ## 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 - V2
> The newest version of this API generates a personalized form link by overlaying fillable fields onto a custom PDF or image background. It also includes additional field types and support for Base64 file uploads.
The API creates a unique form URL that can be shared with customers for completion.
### How It Works
1. Specify the form template to use (via Form ID).
2. Identify the recipient (email or phone number).
3. Add additional parameters to prefill some or all the fields (optional).
4. Add **submissionContext** (optional) that will be attached to the document and enable internal classification used by the organization.
5. Upload a background document (PDF or image) in ONE of the ways (selecting both will fail the API return process).
6. Receive a unique form link to share with the customer
## 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
- `properties` (optional): JSON object with values for form’s inputs fields.
Expected format: field1_name:{field1_value};field2_name:{field2_value}
- `submissionContext` (optional): Internal-only metadata passed in webhooks
- `file` **(required)**: Background document file (PDF or image format URL)
- `base64Data` (Optional): A Base64-encoded PDF uploaded with the request combined with the file name.
Expected format for field’s value: filename:{file_name};base64:{base64_string}
## 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 /v2/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": {
"/v2/forms/createpredefinedlink/{FORM_ID}": {
"post": {
"tags": [
"Forms"
],
"summary": "Create Predefined Form Link - V2",
"description": "The newest version of this API generates a personalized form link by overlaying fillable fields onto a custom PDF or image background. It also includes additional field types and support for Base64 file uploads.
The API creates a unique form URL that can be shared with customers for completion.\n\n### How It Works\n\n1. Specify the form template to use (via Form ID).\n2.\tIdentify the recipient (email or phone number).\n3.\tAdd additional parameters to prefill some or all the fields (optional).\n4.\tAdd **submissionContext** (optional) that will be attached to the document and enable internal classification used by the organization. \n5.\tUpload a background document (PDF or image) in ONE of the ways (selecting both will fail the API return process).\n6.\tReceive a unique form link to share with the customer\n\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- `properties` (optional): JSON object with values for form’s inputs fields.
Expected format: field1_name:{field1_value};field2_name:{field2_value}\n- `submissionContext` (optional): Internal-only metadata passed in webhooks\n- `file` **(required)**: Background document file (PDF or image format URL)\n- `base64Data` (Optional): A Base64-encoded PDF uploaded with the request combined with the file name.
Expected format for field’s value: filename:{file_name};base64:{base64_string}\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": "v2/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
},
"properties": {
"type": "object",
"description": "(Optional) JSON object with values for form inputs. "
},
"submissionContext": {
"type": "string",
"description": "(Optional) An internal-only metadata passed in webhooks"
},
"file": {
"type": "string",
"format": "binary",
"description": "Background document file (PDF or image format). Upload the file to the Value section"
},
"base64Data": {
"type": "string",
"description": "(Optional) A Base64-encoded PDF uploaded with the request combined with the file name"
}
}
}
}
}
},
"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"
}
}
}
}
}
}
}
}
}
}
}
````