Overview
The Cloudcheck Go API service enables you to send a secure link to your customers, allowing them to self-verify. Each Go request can provide this functionality for up to 500 of your customers (or "recipients" in Go terminology).
The methods available to send the links to your customers are flexible. You can have Cloudcheck send them an email or SMS. Alternatively you can download the links and send them yourself, or you can incorporate the link in your own system creating a seamless experience for your customers.
If offers the same functionality as the Go feature within Cloudcheck Direct and they can both work together. For example, you can create a Go request using the API, then login to Cloudcheck Direct and view the request. You could continue the process using either the API or Direct.
Create
| Path | /go/create/ | Method | POST |
|---|
Creates a new Go request. Everything required by Go can be included in the request, including up to 500 recipients.
When creating a Go 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 to be verified. |
Request
The details to be verified must be supplied as a JSON object, included in the POST as the data parameter. All the request parameters need to be included in the signature generation, and the request signed with the private key provided to you.
This API will validate each recipient and will not load it into the system if it's invalid. There must be at least 1 valid recipient for the request to succeed.
Example
This example shows the typical elements passed to the API for a recipient.
EitheremailAddressormobileNumbermust be provided.{"reference": "Go reference 101","notifications": true,"notificationEmailAddress": "bogus@myorganisation.com","sendReminders": true,"completeUrl": "https://www.mycompany.com/id-complete","notificationUrl": "https://www.mycompany.com/notify-me","emailFrom": "My Organisation","replyTo": "noreply@myorganisation.com","emailSubject": "Identity Verification Request","emailContent": "Content including <em>allowed</em> HTML tags","recipients": [{"emailAddress": "noreply@verifidentity.com","mobileNumber": "0228880000","reference": "Recipient reference 1","requestType": {"verification": true,"live": false,"idscan": false,"akahu": false,"credfin": false}},...]}
This example shows additional elements that can be passed for each recipient,
if required. Normally the name, address and DOB are left blank, which forces
the end user to enter these details.{"reference": "Go reference 101","notifications": true,"notificationEmailAddress": "bogus@myorganisation.com","sendReminders": true,"completeUrl": "https://www.mycompany.com/id-complete","emailFrom": "My Organisation","replyTo": "noreply@myorganisation.com","emailSubject": "Identity Verification Request","emailContent": "Content including <em>allowed</em> HTML tags","recipients": [{"name": {"given": "Jane","middle": "Marie","family": "Smith"},"emailAddress": "noreply@verifidentity.com","mobileNumber": "0228880000","address": {"suburb": "Hillsborough","street": "27 Indira Lane","postcode": "8022","city": "Christchurch","countryCode": "NZ"},"dateofbirth": "1978-01-10","reference": "Recipient reference 1","requestType": {"verification": true,"live": false,"idscan": false,"akahu": false,"credfin": false}},...]}
Data Element Notes
| Element | Notes |
|---|---|
| reference | A reference that you provide to identify this Go request. Optional but recommended. |
| notifications | If true, you will be sent a notification email every time a user completes verification. Optional, defaults to false. |
| notificationEmailAddress | Comma-separated list of email address that notifications are sent to. Mandatory if notifications is true. |
| sendReminders | If true, recipients will get a reminder email after 5 days if they haven't performed their verification. Optional, defaults to false. |
| completeUrl | Where to redirect users after completing the verification. Include the protocol at the start of the URL (https:// or http://). This element is optional but highly recommended. A token parameter will be added to the URL that can be used in the Go Result and PDF Result API calls, to fetch the results for this recipient in either json or PDF format. If you do not specify a completeUrl the user will be redirected to a default "thank you" page. |
| notificationUrl | A URL that we will call when the status of a recipient in this request changes. Include the protocol at the start of the URL (https:// or http://). A goApiReference parameter will be added to the URL that identifies the Go request, a recipientToken parameter identifies the recipient within the Go request and a status parameter gives the new status. |
| emailFrom | Where the email is from, usually the name of your organisation. Mandatory if recipient email addresses have been entered. |
| replyTo | An email address for replies to your organisation. Mandatory if recipient email addresses have been entered. |
| emailSubject | Email subject. Mandatory if recipient email addresses have been entered. |
| emailContent | The content of the email. This content can include safe HTML tags, unsafe tags such as <script> will be removed. |
| recipients | A list of recipients. At least 1 and no more than 500 valid recipients must be provided. |
| name | Standard name fields. |
| emailAddress | The email address of the recipient. |
| mobileNumber | The mobile phone number of the recipient. |
| dateofbirth | The date of birth in yyyy-MM-dd format. |
| address | Standard address fields of the recipient. Must not be a PO Box. Australian addresses would include state and no suburb. |
| reference | A reference that you provide to identify this recipient. Optional but recommended. |
| requestType | Specifies what checks you want the recipient to complete. One or more of verification, live, idscan, akahu or credfin must be true. Live, IDscan, Akahu and Credfin must be configured for your Cloudcheck account in order to use them. |
Response
The response JSON contains the outcome of the request.
Example
A successful response looks like this:
{
"result": "success",
"goApiReference": "cab9d987-4027-4dd9-b5a6-cf547232836c",
"recipients": [
{
"reference": "Recipient Reference 1",
"token": "7063ec21-1d33-4ebb-a498-976e2b23e1ed",
"name": {
"given": "",
"middle": "",
"family": ""
},
"dateofbirth": "1978-01-10",
"emailAddress": "noreply@verifidentity.com",
"mobileNumber": "+64220001111",
"status": "Not Sent",
"successful": "",
"respondedDate": ""
}
]
}
A successful response with two recipients removed due to invalid data looks like this:
{
"result": "success",
"goApiReference": "cab9d987-4027-4dd9-b5a6-cf547232836c",
"recipients": [
{
"reference": "Recipient Reference 1",
"token": "7063ec21-1d33-4ebb-a498-976e2b23e1ed",
"name": {
"given": "Donald",
"middle": "",
"family": "Trump"
},
"address": {
"street": "27 Indira Lane",
"suburb": "Hillsborough",
"city": "Christchurch",
"postcode": "8022",
"countryCode": "NZ"
},
"dateofbirth": "1978-01-10",
"emailAddress": "noreply@verifidentity.com",
"mobileNumber": "+64220001111",
"status": "Not Sent",
"successful": "",
"respondedDate": ""
},
...
],
"warning": "2 invalid recipients were discarded",
"invalidRecipients": [
{
"recipientIndex": 23,
"validationErrors": [
{
"code": "MISSING_SERVICE",
"message": "Please select either verification, Cloudcheck Live or Akahu."
}
]
},
{
"recipientIndex": 124,
"validationErrors": [
{
"code": "MISSING_SERVICE",
"message": "Please select either verification, Cloudcheck Live or Akahu."
}
]
}
]
}
The goApiReference returned in a successful response is a unique reference for this request and is used in the other Go API requests.
Possible error codes for invalid recipients and their error codes are:
| Code | Description |
|---|---|
| INVALID_PHONE_NUMBER | Enter a mobile number including the country code (eg. +64). |
| INVALID_DATE_OF_BIRTH | Invalid date of birth |
| INVALID_ADDRESS | Invalid address |
| MISSING_SERVICE | Please select either verification or an additional measure (e.g. Cloudcheck Live, IDscan, Akahu or Credfin). |
| SERVICE_NOT_AVAILABLE | An additional measure (e.g. Live, IDscan, Akahu or Credfin) has been requested but is not available. |
Add Recipient
| Path | /go/add-recipient/ | Method | POST |
|---|
Add a recipient to an existing Go 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. |
data |
true | A JSON string containing the details of the recipient. |
Request
The recipient details must be supplied as a JSON object, included in the POST as the data parameter. All the request parameters need to be included in the signature generation, and the request signed with the private key provided to you.
This API will validate the recipient and will not load it into the system if it's invalid.
Example
{
"goApiReference": "cab9d987-4007-4dd9-b5a6-cf547232836c",
"recipient": {
"reference": "Recipient reference 1",
"emailAddress": "noreply@verifidentity.com",
"mobileNumber": "+64221234567",
"requestType": {
"verification": true,
"live": false,
"idscan": false,
"akahu": false,
"credfin": false
}
}
}
Note that additional elements can be sent for a recipient, however this is the typical information supplied. See the Go Create API example for details of additional elements available.
Response
The response JSON contains the outcome of the request. A successful response is shown in the following example.
Example
{
"result": "success",
"recipientToken": "3063ec0a-5d33-4ebb-a498-2b6e2b23e1ed"
}
The recipientToken uniquely identifies the recipient within the Go request and can be used in other Go API calls.
Edit Recipient
| Path | /go/edit-recipient/ | Method | POST |
|---|
Edit a recipient in an existing Go 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. |
data |
true | A JSON string containing the details of the recipient. |
Request
The recipient details must be supplied as a JSON object, included in the POST as the data parameter. All the request parameters need to be included in the signature generation, and the request signed with the private key provided to you.
This API will validate the recipient and will not load it into the system if it's invalid.
If successful, the existing recipient will be completely replaced by the details supplied in this call.
Example
{ "goApiReference": "cab9d987-4007-4dd9-b5a6-cf547232836c", "recipient": { "token": "7063ec01-1d33-4ebb-a498-976e2b23e1ed", "reference": "Recipient reference 1", "emailAddress": "noreply@verifidentity.com", "mobileNumber": "+64221234567", "requestType": { "verification": true, "live": false, "idscan": false, "akahu": false, "credfin": false } }}
Note that additional elements can be sent for a recipient, however this is the typical information supplied. See the Go Create API example for details of additional elements available.
Response
The response JSON contains the outcome of the request. A successful response is shown in the following example.
Example
{ "result": "success", "recipientToken": "3063ec0a-5d33-4ebb-a498-2b6e2b23e1ed"}
Note: the recipientToken will change if a recipient emailAddress or mobileNumber has changed and an email/SMS has already been sent. In this scenario the old recipientToken will no longer be valid.
Cancel Recipient
| Path | /go/cancel-recipient/ | Method | POST |
|---|
Cancel a single or multiple recipients in an existing Go request.
Request
The recipient details must be supplied as a JSON object, included in the POST as the data parameter. All the request parameters need to be included in the signature generation, and the request signed with the private key provided to you.
This API will check if the recipient exists in the system.
If successful, the existing recipient will be cancelled by the token supplied in this call.
Example
{
"recipients": [
{
"token": "243266b4-760e-4d9c-8c69-1852111309b5"
}
]
}Response
The response JSON contains the outcome of the request. A successful response is shown in the following example.
Example
{
"recipients": [
{
"result": "success",
"token": "e26df8dc-341c-4f21-abf2-4cc71cf99c64"
} ]
}Send
| Path | /go/send/ | Method | POST |
|---|
There are two use cases for using this API.
The first is to send a test email and/or SMS message. It is not a requirement that you send a test email/SMS before sending the real email/SMS to recipients. One reason you might want to send a test is to check that the email looks correct. If you want to change the wording or formatting of the email after the test you can use the Go functionality with Cloudcheck Direct to modify the email contents.
The second is to send emails and/or SMS's to the recipients in this Go request.
When calling this API, 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 to be verified. |
Request
The behaviour of the Send request is specified using the data parameter, which is a JSON object.
Example
A request to send a test email and/or SMS has the following format:
{
"goApiReference": "cf61fd1f-6cb6-4972-b95b-adf329c718a6",
"email": true,
"sms": true,
"test": true,
"testMobileNumber": "0221860527"
}
The goApiReference was returned in the Go Create API response and is mandatory.
The email and sms elements control whether test emails and/or SMSs are sent. They are both optional and default to true.
The test element indicates that you want to sent a test only and must be set to true. This is an optional element which defaults to false (in which case emails and/or SMSs will be sent to each recipient).
The testMobileNumber is where the test SMS is sent to and is mandatory if test is true and sms is true.
A request to send an email and/or SMS to each recipient has the following format:
{
"goApiReference": "cf61fd1f-6cb6-4972-b95b-adf329c718a6",
"email": true,
"sms": true
}
Response
The response JSON contains the results of the Send request.
Example
A successful response looks like this:
{
"result": "success",
"numberOfEmailSent": 122,
"numberOfSmsSent": 12
}
Resend
| Path | /go/resend/ | Method | POST |
|---|
Resend an email/SMS to a recipient within this Go 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. |
data |
true | A JSON string containing the details of the Go request and recipient. |
Request
The Go request and recipient identifiers must be supplied as a JSON object, included in the POST as the data parameter. All the request parameters need to be included in the signature generation, and the request signed with the private key provided to you.
Example
{ "goApiReference": "cf61fd1f-6cb6-4972-b95b-adf329c718a6", "recipientToken": "7063ec01-1d33-4ebb-a498-976e2b23e1ed"}
Response
The response JSON contains the outcome of the request. A successful response is shown in the following example.
Example
{ "result": "success", "resendMethod": "email"}
Download Links
| Path | /go/links/ | Method | GET |
|---|
Creates a link (or URL) for each recipient in the Go request. This API is an alternative to the Go Send API. Each link can be sent to the appropriate recipient to allow them to self-verify. The sending of the link to each recipient is your responsibility.
| 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. |
goApiReference |
true | The unique reference that was returned in the Go Create response. |
Response
The JSON response contains the details you have provided for each recipient, along with a link that will allow them to self-verify.
Example
{"links": [{"reference": "Recipient Reference 1","name": {"given": "Jane","middle": "Marie","family": "Smith"},"emailAddress": "noreply@verifidentity.com","mobileNumber": "+64221234567","verification": true,"capture": false,
"idscan": false,"akahu": false,
"credfin": false,"link": "https://mysite.cloudcheck.co.nz/cloudcheck/verification/e93e0add-e6e7-410b-84ca-4t46166daa7d/"},...]}
Quick Send
| Path | /go/quicksend/ | Method | POST |
|---|
Allows you to quickly send an email or SMS with minimal information required.
When creating a Go Quick Send 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 to be verified. |
Request
The details to be verified must be supplied as a JSON object, included in the POST as the data parameter. All the request parameters need to be included in the signature generation, and the request signed with the private key provided to you.
Example
{
"reference": "Go quick send reference 101",
"givenName": "Donald",
"generateLink": false,
"emailAddress": "noreply@verifidentity.com",
"mobileNumber": "+64221234567",
"completeUrl": "https://www.mycompany.com/id-complete?id=1234",
"notificationUrl": "https://www.mycompany.com/notify-me",
"requestType": {
"verification": true,
"live": false,
"idscan": false,
"akahu": false,
"credfin": false
}
}
Notes:
- Either
emailAddressormobileNumbermust be provided ifgenerateLinkisfalse. - One or more elements in
requestTypemust betrue. - Users will be redirect to the
completeUrlafter completing the verification. Include the protocol at the start of the URL (https:// or http://). This element is optional but highly recommended. A token parameter will be added to the URL that can be used in the Go Result and PDF Result API calls, to fetch the results for this recipient in either json or PDF format. If you do not specify acompleteUrlthe user will be redirected to a default "thank you" page. - The
notificationUrlis a URL that we will call when the status of the recipient in this request changes. Include the protocol at the start of the URL (https:// or http://). AgoApiReferenceparameter will be added to the URL that identifies the Go request, arecipientTokenparameter identifies the recipient within the Go request and astatusparameter gives the new status.
Response
The response JSON contains the outcome of the request.
Example
{ "result": "success", "goApiReference": "cab9d987-4007-4dd9-b5a6-cf547232836c", "recipientToken": "4fb19522-2ec1-48f4-ac2e-18fc9f17964b",}
The goApiReference returned in a successful response is a unique reference for this request and is used in the other Go API requests. The recipientToken can also be used in other APIs, such as fetching the results of the Go request.
Result
| Path | /go/result/ | Method | GET |
|---|
Fetches the verification result for an individual recipient. You must include the following parameters as part of the call.
| 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. |
token |
true | A recipient token. This token is passed as a parameter to the |
Response
An example response is shown below.
Example
{
"reference": "Recipient Reference 1",
"token": "8e53ec01-1d33-4ebb-a498-976e2b23e1ed",
"name": {
"given": "John",
"middle": "",
"family": "Key"
},
"address": {
"street": "27 Indira Lane",
"suburb": "Hillsborough",
"city": "Christchurch",
"postcode": "8022",
"countryCode": "NZ"
},
"dateofbirth": "1978-01-10",
"emailAddress": "somebody@verifidentity.com",
"mobileNumber": "+64220001111",
"status": "Not Sent",
"successful": "Yes",
"respondedDate": "2021-05-01 11:23",
"verification": {
// standard verification fields
},
"capture": {
// standard Live fields
},
"credfin": {
// standard Credfin fields
},
"akahu": {
// standard Akahu fields
},
"idscan": {
// standard IDscan fields
}
}
Refer to the Integrated Verification API response for standard verification fields.
Refer to the Live Result API response for standard Live fields.
Refer to the Credfin Result API response for standard Credfin fields.
Refer to the Akahu Result API for standard Akahu fields.
Refer to the IDscan Result API for standard IDscan fields.
Results
| Path | /go/results/ | Method | GET |
|---|
Fetches the verification results for each recipient at this point in time in JSON format.
| 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. |
goApiReference |
true | The unique reference that was returned in the Go Create response. |
Response
An example response is shown below:
Example
{
"reference": "Go API notification test 1",
"createdDate": "2020-04-23 16:07",
"summary": {
"totalRequests": 2,
"responsesReceived": 1,
"passCount": 1,
"partialCount": 0,
"liveOnlyCount": 0,
"liveProOnlyCount": 0,
"akahuOnlyCount": 0,
"idscanOnlyCount": 0,
"failureCount": 0,
"watchlistMatchCount": 0
},
"recipients": [
{
"reference": "Recipient Reference 1",
"token": "7063ec01-1d33-4ebb-a498-976e2b23e1ed",
"name": {
"given": "Jane",
"middle": "Marie",
"family": "Smith"
},
"emailAddress": "noreply@verifidentity.com",
"mobileNumber": "+64221860527",
"status": "Not Sent",
"successful": ""
},
{
"reference": "Recipient Reference 2",
"token": "ca23ec01-1d33-4ebb-a498-976e2b23e1ed",
"name": {
"given": "",
"middle": "",
"family": ""
},
"emailAddress": "noreply@verifidentity.com",
"mobileNumber": "",
"status": "Responded",
"successful": "Yes",
"verification": {
"reference": "API-20200507-1129",
"verificationSuccess": true,
"validated": {
"name": true,
"namePassCount": 1,
"address": true,
"addressPassCount": 1,
"dateofbirth": false
},
"sources": [
{
"name": "LINZ",
"success": true,
"error": false
}
],
"verificationReference": "b9c0f331-24aa-40a8-a5f2-9d1d3566fb90",
"requestDate": "2020-04-23 16:08",
"ipAddress": "192.168.1.20",
"details": {
"address": {
"city": "Auckland",
"street": "12 My Street",
"postcode": "1052",
"suburb": "Parnell"
},
"name": {
"given": "Arnold",
"middle": "Alois",
"family": "Schwarzenegger"
},
"nameChanged": false
},
"verificationPartialSuccess": true,
"verificationDate": "2020-04-24 08:30"
}
}
]
}
The possible values for the recipient status element are: Not Sent, Sent, Delivered, Bounced, Delayed, Rejected, Opened, Clicked, Expired and Responded. A status of Expired can either mean that the user did not complete the verification before it expired, it can also mean that the user completed part of the verification but then cancelled before they finished. Therefore you should fetch the results of the verification when the status is Responded or Expired.
PDF Result
| Path | /go/pdf/ | Method | GET |
|---|
Fetches the verification result for an individual recipient in PDF format. You must include the following parameters as part of the call.
| 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. |
token |
true | A recipient token. This token is passed as a parameter to the |
Response
This method will either return a PDF file or a JSON object with an error message. You should check the response Content-Type to determine which you have received.
Generate PDF Results
| Path | /go/pdfs/generate/ | Method | GET |
|---|
Requests the generation of PDF results for each recipient that has responded. This is a time consuming process that can take around an hour to complete for 500 recipients, therefore it is an asynchronous operation. First you request that the PDFs are generated, using this API. Then you call the Retrieve PDF Results API to download a zip file containing the PDFs.
| 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. |
goApiReference |
true | The unique reference that was returned in the Go Create response. |
Response
An example response looks like this:
Example
{
"result": "success",
"token": "cab9d982-4007-4dd9-b5a6-cf547232836c"
}
The token that is returned is used in the Retrieve PDF results request.
Retrieve PDF Results
| Path | /go/pdfs/retrieve/ | Method | GET |
|---|
Retrieves a zip file containing the PDF results of each recipient that has responded. If the generation of the PDFs is still in progress a JSON response is returned instead, with the status of the job.
If another response is received from an end user after the PDF results were generated this call will result in a 'Missing or invalid token' error as the results are no longer current. In this case you will need to generate the results again.
| 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. |
token |
true | The |
Response
If the PDF generation is complete a zip file will be returned containing the PDF documents. If the generation is still in progress the following JSON will be returned:
Example
{
"status": "Pending"
}