Receipt Generation

Often solutions will require a simple human-readable ID to allow users to easily reference their form submission. To cater for this requirement we have created the Receipt Generation feature allowing you to create custom Receipt Ids as part of your form submission process. 

There are two ways to create a Receipt ID, one is generating it using the built-in Receipt ID feature, and the second is using an API. 

TABLE OF CONTENTS

• Receipt ID
• Custom URL and Hosted API
• Add New Component
• Presenting the Receipt ID to Users

Receipt ID

To create your Receipt ID without needing to create an API or use the Receipt ID option on the Developer Tools tab of your form. The Receipt ID will be an 8-character random string created from numbers and uppercase letters by default or you can customise this Receipt ID by adding additional components. 

Components come in 4 types Text, Date, Random and Sequential Numbers. You can choose to add any number of these to your Receipt ID. The exception to this is Sequential Numbers which you can only have 1 of in any Receipt ID. 

In the example below I have added a Text prefix (Pre-), the month (MM), the date (DD), another text (-) and a random 8-character string consisting of uppercase letters, lowercase letters and numbers. An example of the Receipt ID will be displayed to show how your components will affect the Receipt ID. 

IMPORTANT NOTE - If you want to guarantee that the Receipt IDs being generated are unique to each submission you will need to include a Sequential Number component.

Add New Component

Adding a new component to Receipt Generation allows users to add a modifier to customise how the receipt is generated.

Text: Generates a piece of text that will be displayed on every receipt. This can be used to add prefixed or separate the different sections of the Receipt ID but using a dash (-) such as in the example above. 

Dates: Generates a specific chosen type of date in the Receipt. These can be used to create a specific date format for your users and allow you to know when the submission was completed by looking at the date section of the Receipt ID.

Random: Adds randomly generated text and or numbers to Receipts. Choose the number of characters and then what character sets to include. To avoid confusion for users we remove similar appearing characters in the generated Receipt ID (i, I, l, L, o, O, 0).

Sequential Number: Generates a sequential number for every submission. You can enter a starting number allowing you to begin the sequence at a higher number. Note that once the form is submitted a starting number cannot be added or modified.

Custom URL and Hosted API

If you need to generate a Receipt ID that cannot be catered for using the out-of-the-box Receipt ID functionality, then you will need to add a custom URL or a hosted API endpoint. This endpoint will be called on form submission and allow you to generate an external ID.

Example

Below is a type definition of the request payload

{ 
   formsAppId: number
    formId: number
    externalIdUrlSearchParam: string | null
    draftId: string | null
    preFillFormDataId: string | null
    jobId: string | null
    previousFormSubmissionApprovalId: string | null
    submission: Record<string, unknown>
}

{ 
    externalId?: string 
}

The External ID is required in the response payload if the externalIdUrlSearchParam is provided in the request payload.

Error Handling

The only HTTP status we support for error handling when generating a receipt number via an API is400with a response payload like so:

{
  "message": "<p>pretty html error message can go here</p>"
}

Presenting the Receipt ID to Users

Submission Message

To display the Receipt ID to your users you can add it in the successful submission message. 

To do so go to the Buttons configuration on the Forms Settings tab. Turn on the switch to "Customise the success message". This will allow you to customise the Submission message. Clicking "Use Default" will help you get started, and then adding the {EXTERNAL_ID} into the Submission Message will allow users to see their Receipt ID once they complete the form. See the example below.

Creating a Receipt Page

If you instead want to redirect the user to another form and display the Receipt ID there, you do so using the OneBlink pre-fill, and redirect URL functionality. Create your receipt page and add the URL of your Receipt page as a redirect URL to your form. 

Add the below text to the end of the redirect URL, be sure to add the name of the element you want to pre-fill with the external ID. This will ensure that an element on your Receipt page is populated with the Receipt ID.

?preFillData={"name of your element":"{EXTERNAL_ID}"}

Get Help

If you have any questions or would like assistance with setting up your Receipt Generation please contact us via this support portal or email [email protected]. We are happy to assist in any way we can.