Create Predefined Form Link

  • Published on Feb 12, 2026
  • 2 minute(s) read
  • EM
 Prev Next
Post
/forms/createpredefinedlink/{FORM_ID}

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

Security
HTTP
Type bearer

API key is needed to authorize requests. You can get your API key via the management console.
A Bearer Token is needed to be set in the Authorization header of every API call.
For additional support you can contact us.

Path parameters
FORM_ID
stringRequired

Form Id - Form number (as seen on the forms list screen)

Body parameters
object
streamProviderId
string Required

The identifier of the receiving customer by their phone number or email

Example19175552345
streamProviderType
string Required

4 for email, 5 for phone number

Valid values[ "4", "5" ]
Example5
referringObjectId
integer

(optional) The object ID of the conversation related to the Form

Example312345
file
string (binary)

Background document file (PDF or image format). Upload the file to the Value section

Responses
200

OK

Expand All
object
status
integer
Example200
description
string
ExampleOperation successful
response_time
string (date-time)
Example2025-02-06T07:51:52.258Z
data
object
conversation_id
string

The ID of the conversation linked to this form

Example312345
form_link
string (uri)

The unique URL for the generated form

Examplehttps://apps.commbox.io/form/commbox/499fdc93aa804a4b8266251224944d6a
400

Bad Request - The request could not be understood by the server. Incoming parameters might not be valid

Expand All
object
status
integer
Example400
description
string
ExampleBad Request
response_time
string (date-time)
Example2025-02-06T07:51:52.258Z
error
object
code
string
ExampleINVALID_PARAMETER
message
string
ExampleInvalid streamProviderType. Must be 4 (email) or 5 (phone)
details
Array of object
object
field
string
ExamplestreamProviderType
issue
string
ExampleValue must be either 4 or 5
401

Unauthorized - The supplied credentials, if any, are not sufficient to access the resource

Expand All
object
status
integer
Example401
description
string
ExampleUnauthorized
response_time
string (date-time)
Example2025-02-06T07:51:52.258Z
error
object
code
string
ExampleAUTHENTICATION_FAILED
message
string
ExampleInvalid or missing authentication credentials
404

Not found - The requested resource is not found

Expand All
object
status
integer
Example404
description
string
ExampleNot Found
response_time
string (date-time)
Example2025-02-06T07:51:52.258Z
error
object
code
string
ExampleFORM_NOT_FOUND
message
string
ExampleForm with ID 'FORM_ID' does not exist
429

Too Many Requests - Too many requests have been made in a short period of time (Throttling)

Expand All
object
status
integer
Example429
description
string
ExampleToo Many Requests
response_time
string (date-time)
Example2025-02-06T07:51:52.258Z
error
object
code
string
ExampleRATE_LIMIT_EXCEEDED
message
string
ExampleRate limit exceeded. Please try again later
retry_after
integer

Seconds until the rate limit resets

Example60
500

Server Error - The server could not return the representation due to an internal server error

Expand All
object
status
integer
Example500
description
string
ExampleInternal Server Error
response_time
string (date-time)
Example2025-02-06T07:51:52.258Z
error
object
code
string
ExampleINTERNAL_ERROR
message
string
ExampleAn unexpected error occurred. Please try again later
trace_id
string

Internal trace ID for debugging

Examplea3b5c7d9-e1f3-4567-89ab-cdef01234567