Overview
Cloudcheck Forms allows end-to-end onboarding with customisable application forms integrated with Cloudcheck Go.
Create
| Path | /forms/create/ | Method | POST |
|---|
Creates a new Forms request. You must include the following parameters as part of the call. Please note all these parameters must be posted as URL encoded form data. As such, the request should contain a Content-Type header of application/x-www-form-urlencoded.
| Parameter | Required | Description |
|---|---|---|
key |
true | Your API Key. |
signature |
true | An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature. |
nonce |
true | A single-use key generated for this request. Note that each nonce may only be used once for each access key. |
timestamp |
true | The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected. |
data |
true | A JSON string containing the details of the Forms request. |
Request
An example of the JSON in the data parameter is shown below.
Example
{ "reference": "Forms reference 101", "emailAddress": "bogus@xyz.com", "givenName": "Mike", "emailCcAddress": "bogus@xyz.com", "notificationUrl": "https://www.mycompany.com"}
Data Element Notes
| Element | Notes |
|---|---|
| reference | A reference that you provide to identify this Forms request. Optional but recommended. |
| emailAddress | Address used to send the email asking for the initial form to be completed. Both emailAddress and givenName must be supplied if an email is to be sent, otherwise these fields will be ignored and a link will be generated instead. |
| givenName | The given name of the person the initial email is sent to. |
| emailCcAddress | Added as a cc address for the email asking for the initial form to be completed. Also receives an email when the last person verifies themselves. |
| notificationUrl | A notification is sent to this URL when the form is submitted, as well as when the last person verifies themselves. Two parameters are added to this URL: reference - identifies the forms request, and status - indicates the status of the forms request, e.g. SUBMITTED or COMPLETED. |
Response
An example of the JSON returned in the response is shown below:
Example
{ "result": "success", "formsReference": "ea15d4e4-bc9d-4b4e-8aad-7b6b88b032d4", "emailSent": true, "link": "https://forms.cloudcheck.co.nz/forms/requests/e2b9d987-4007-4dd9-b5a6-cf547232836c/"}
The formsReference is a unique identifier for this forms request and is used in the other Forms API calls.
The emailSent is a boolean parameter indicating whether an email was automatically sent or not. An email is only sent if both emailAddress and givenName was supplied in the request.
The link is the URL that was sent in the email. If an email wasn't automatically sent it is up to you to send this link to the person who will be responsible for filling out the initial form.
Resend
| Path | /forms/resend | Method | POST |
|---|
Allows a Forms request to be resent. You must include the following parameters as part of the call. Please note all these parameters must be posted as URL encoded form data. As such, the request should contain a Content-Type header of application/x-www-form-urlencoded.
| Parameter | Required | Description |
|---|---|---|
key |
true | Your API Key. |
signature |
true | An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature. |
nonce |
true | A single-use key generated for this request. Note that each nonce may only be used once for each access key. |
timestamp |
true | The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected. |
data |
true | A JSON string containing the details of the Forms request. |
Request
An example of the JSON in the data parameter is shown below.
Example
{ "formsReference": "ea15d4e4-bc9d-4b4e-8aad-7b6b88b032d4", "emailAddress": "bogus@xyz.com", "givenName": "Mike"}
The formsReference is mandatory and identifies the Forms request to resend.
The givenName and emailAddress of the user receiving the email request are optional but can be supplied if changes are required.
Response
An example of the JSON returned in the response is shown below:
Example
{ "result": "success"}
Result
| Path | /forms/result/ | Method | GET |
|---|
Fetches the current result of the forms request.
| Parameter | Required | Description |
|---|---|---|
key |
true | Your API Key. |
signature |
true | An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature. |
nonce |
true | A single-use key generated for this request. Note that each nonce may only be used once for each access key. |
timestamp |
true | The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected. |
reference |
true | A unique identifier for the forms request, returned as |
Response
An example of the JSON returned in the response is shown below:
Example
{ "status": "COMPLETED", "formsReference": "eab9d987-40b7-4dd9-b5a6-cf547232836c", "reference": "Forms Request 102345", "apiRequest": false, "requestedBy": "John Smith", "createdDate": "2022-12-10 15:04", "updatedDate": "2022-12-12 11:22", "emailAddress": "bogus@gmail.com", "emailCcAddress": "bogus2@gmail.com", "givenName": "Michael", "emailStatus": "Delayed", "goRequests": [ { "reference": "Forms: a42511a2-ac30-408c-ba58-8f2a5c139a58", "goApiReference": "a42511a2-ac30-408c-ba58-8f2a5c139a58", "createdDate": "2022-12-11 17:42", "recipientCount": 10, "respondedCount": 10 }, ... ]}
The values of status can be:
- PENDING - the forms request has been created however the form hasn't been filled out yet
- SUBMITTED - the form has been filled out and submitted, or
- COMPLETED - all recipients have verified themselves
One or more goRequests may exist. Use the goApiReference to fetch the details of the Go request using our Go APIs.
Download
| Path | /forms/download/ | Method | GET |
|---|
Fetches a download link for this forms request.
| Parameter | Required | Description |
|---|---|---|
key |
true | Your API Key. |
signature |
true | An HMAC SHA-256 signature of request data for call validation. See details on generating a request signature. |
nonce |
true | A single-use key generated for this request. Note that each nonce may only be used once for each access key. |
timestamp |
true | The system timestamp when the request was created in milliseconds since the Epoch (timezone independent). Note Unix time is in seconds and will need to be multiplied by 1000. Requests with old timestamps will be rejected. |
reference |
true | A unique identifier for the forms request, returned as |
Response
If this request is successful the response JSON will looks something like this:
Example
{ "status": "success", "downloadUrl": "https://formsbyair.com/documents/deliveries/...."}
The downloadUrl is a short-lived URL that you can call to download the complete results of the Forms request at this point in time.
This file is usually a zip file for a completed request, containing the intial form, each verification result, as well as any other supporting documentation and files that were uploaded during the process. However, for simple form requests, or incomplete requests, the download file may be a single PDF.