API

Running Ultradox from your own application or website is simple.

Introduction

Running Ultradox from your own application or website is simple.

Just call the URL of your flow and pass the content that your flow needs either as parameters in the URL or in the body of the request.

You can either run the flow, download the generated document or embed your app into your website.

We have composed a couple of examples how to invoke Ultradox on different platforms.

You can copy and paste those snippets into your application or website to get started instantly. At the bottom of this page you will find the supported data formats reference.

Generate API key

Access to your flow is authorized by the Ultradox key. The key is part of the URL, so creating a new key will revoke access to your flow.

Run

When[a][b] calling the URL to run your flow, all building blocks will be executed just as if you would press the Run button in the Ultradox editor.

You can watch and debug the execution in the Ultradox editor when triggering your flow via the URL.

Ultradox will return an execution report in JSON format that gives you information about the steps that have been executed. 

# Execute in your shell to run your flow
curl http://www.ultradox.com/run/[your key goes here]

<a href="http://www.ultradox.com/run/[your key goes here]" target="_blank">Click to run</a>

// Execute in your App Script function to run your flow
var response = UrlFetchApp.fetch('http://www.ultradox.com/run/[your key goes here]');
var code = response.getResponseCode();

URL url = new URL("http://www.ultradox.com/run/[your key goes here]");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
int code = connection.getResponseCode();
Logger.getLogger("StaticTrigger").info(code == HttpURLConnection.HTTP_OK ? "Success" : "Error: " +code);

URL url = new URL("http://www.ultradox.com/run/[your key goes here]");
URLFetchService urlFetchService = URLFetchServiceFactory.getURLFetchService();
HTTPRequest request = new HTTPRequest(url, HTTPMethod.GET, withDefaults().setDeadline(30.0));
HTTPResponse response = urlFetchService.fetch(request);
int code = response.getResponseCode();

// this example uses jQuery to make a painless JSONP call
$.getJSON("http://www.ultradox.com/jsonp?id=[your key goes here]&action=RUN&callback=?", null,
function(response) {
var code = response.code; // "ok" or "error"
var message = response.message;
}
);

Download

If your flow is generating a document (e.g. a PDF or Word document) you can download it by invoking the download URL.

In the following examples we have already specified a sample flow generating a document to get you started.

Feel free to try out the snippets and download the provided example. 

# Execute in your shell to save result to a file called processed.pdf
curl http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU > processed.pdf

<a href="
http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?filename=mydocument.pdf
" target="_blank">Click to Download</a>

// Retrieve generated PDF using UrlFetch
var response = UrlFetchApp.fetch('http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU');
// Store generated PDF in a blob
var blob = response.getBlob();

URL url = new URL("http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU");
InputStream inputStream = url.openStream();
FileOutputStream outputStream = new FileOutputStream(new File("processed.pdf"));
transfer(inputStream, outputStream);

URL url = new URL("http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU");
URLFetchService urlFetchService = URLFetchServiceFactory.getURLFetchService();
HTTPRequest request = new HTTPRequest(url, HTTPMethod.GET, withDefaults().setDeadline(30.0));
HTTPResponse response = urlFetchService.fetch(request);
byte[] content = response.getContent();

Passing parameters (GET)

Some flows allow or even require additional parameters to be passed upon invocation.

When calling Ultradox you can simply add those parameters to the URL.

Again we have used the key of a sample document that gets downloaded. Replace the string JaFxzA9G0ac4Npx83lvY78M9kO5lNO with your own key to run your own flow. 

# Pass position, dateOfInterview and refused as URL parameters
curl http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU
?position=Sales%20Representative&dateOfInterview=2014-01-31&refused=false
>processed.pdf

<a href="http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?position=Sales%20Representative&dateOfInterview=2014-01-31&refused=false" target="_blank">Create and Download</a>

function getParameters() {
var response = UrlFetchApp.fetch('http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?position=Sales%20Representative&dateOfInterview=2014-01-31&refused=true');
var blob = response.getBlob();
var code = response.getResponseCode();
Logger.log(code === 200 ? "Success" : "Error Code: " + code);
// sending out email just for demo purposes
// in real applications send out personalized emails using Ultradox instead
GmailApp.sendEmail("[your email goes here to send this to yourself]", "Your generated document",
"See attachment",
{ attachments: [
{ fileName: blob.getName(),
mimeType: "application/pdf",
content: blob.getBytes()
}
]
}
);
}

URL url = new URL("http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?position=Sales%20Representative&dateOfInterview=2014-01-31&refused=true");
InputStream inputStream = url.openStream();
FileOutputStream outputStream = new FileOutputStream(new File("processed.pdf"));
transfer(inputStream, outputStream);

URL url = new URL("http://www.ultradox.com/download?WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?position=Sales%20Representative&dateOfInterview=2014-01-31&refused=true");
URLFetchService urlFetchService = URLFetchServiceFactory.getURLFetchService();
HTTPRequest request = new HTTPRequest(url, HTTPMethod.GET, withDefaults().setDeadline(30.0));
HTTPResponse response = urlFetchService.fetch(request);
byte[] content = response.getContent();

Complete examples on GitHub

Passing parameters (POST)

Some Ultrdocs allow or even require large data to be passed upon invocation. You can specify those parameters in the body of a POST request either in JSON format or form encoded.

Have a look at the HTML example for form encoded data, all the other examples use the JSON format.

In the examples we have again specified the id of a sample document that gets downloaded using the DOWNLOAD action. You can set your own id by replacing the string JaFxzA9G0ac4Npx83lvY78M9kO5lNO with the integration id of your Ultradoc.

Note: Of course, you can also use the RUN action with POST parameters. 

# Execute in your shell and the processed Ultradoc will be saved to a file called processed.pdf
curl http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU
-X POST
-H "Content-Type: application/json"
-d '{"position": "Sales Representative", "dateOfInterview": "2014-01-31", "refused": "false"}'
> processed.pdf

<form action="http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU" target="_blank">
<input type="text" name="position" required placeholder="Position">
<input type="text" name="dateOfInterview" required placeholder="Date of Interview, format YYYY-MM-DD">
<input type="text" name="refused" required placeholder="Refused: true / false">
<input type="submit" value="Create and Download">
</form>

function postParameters() {
var payload = {
position: "Sales Representative",
dateOfInterview: "2014-01-31",
refused: true
};

var options = {
contentType: "application/json",
method : "post",
payload : Utilities.jsonStringify(payload)
};

var response =
UrlFetchApp.fetch('http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU',
options)
var blob = response.getBlob();
var code = response.getResponseCode();
Logger.log(code === 200 ? "Success" : "Error Code: " + code);

// sending out email just for demo purposes
// in real applications send out personalized emails using Ultradox instead
GmailApp.sendEmail("[your email goes here to send this to yourself]", "Your generated document",
"See attachment",
{ attachments: [
{ fileName: blob.getName(),
mimeType: "application/pdf",
content: blob.getBytes()
}
]
}
);
}

// this example requires GSON: http://code.google.com/p/google-gson/
URL url = new URL("http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("POST");
connection.setRequestProperty("Content-Type", "application/json");
connection.setDoInput(true);
connection.setDoOutput(true);

Gson gson = new Gson();
// have a look at GitHub gist below to see full code for Payload class
Payload payload = new Payload("Sales Representative", "2014-01-31", true);
String json = gson.toJson(payload);
byte[] bytes = json.getBytes();
connection.setRequestProperty("Content-Length", Integer.toString(bytes.length));
OutputStream os = connection.getOutputStream();
os.write(bytes);
os.close();
InputStream inputStream = connection.getInputStream();
FileOutputStream outputStream = new FileOutputStream(new File("processed.pdf"));
transfer(inputStream, outputStream);

// this example requires GSON: http://code.google.com/p/google-gson/
URL url = new URL("http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU");
URLFetchService urlFetchService = URLFetchServiceFactory.getURLFetchService();

Gson gson = new Gson();
// have a look at GitHub gist below to see full code for Payload class
Payload payload = new Payload("Sales Representative", "2014-01-31", true);
String json = gson.toJson(payload);
HTTPRequest request = new HTTPRequest(url, HTTPMethod.POST, FetchOptions.Builder.withDefaults().setDeadline(30.0));
request.setPayload(json.getBytes());
request.setHeader(new HTTPHeader("Content-Type", "application/json"));

HTTPResponse response = urlFetchService.fetch(request);
byte[] content = response.getContent();

Complete examples on GitHub

Passing complex content

When your applications become more complex and you have more than one data set to process and that data might even have a nested structure, you can still use Ultradox.

In that case all you have to do is bring your data in a matching JSON format and pass it along in the body of a POST request.

In the examples we have again specified the id of a sample document that gets downloaded.

Depending on your flow change the structure of the JSON passed accordingly.

The pure HTML solution deserves special attention. Ultradox has a feature that allows you to pass complex objects and even lists of objects using GET requests. This is especially nice when using links in HTML .

To pass properties of objects you simply use the dot notation for the name of a parameter like in object.property .

If you want a list of objects you pass along as many parameters of the same name as you want. If you pass both object.property=Prop1 and object.property=Prop2 as parameters to a GET request, Ultradox will receive a list of objects one having Prop1 as a property, the other Prop2. Have a look at the HTML tab for a complete example. 

# Execute in your shell and the processed Ultradoc will be saved to a file called processed.pdf
curl http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?locale=DE
-X POST
-H "Content-Type: application/json"
-d '{
"name": "Olli",
"events": [
{
"title": "Strategy Meeting",
"startTime": "2014-02-01T10:00:00+01",
"endTime": "2014-02-01T11:30:00+01",
"description": "Discussion of the floreysoft strategy",
"location": "Telemannstraße 22, 20255 Hamburg"
}, {
"title": "Dinner",
"startTime": "2014-02-01T20:00:00+01",
"endTime": "2014-02-01T22:30:00+01",
"description": "Dinner with Le Chef",
"location": "Gaußstraße 3, 22765 Hamburg"
}
]
}'
>processed.pdf

<!-- Manual URL enconding at http://www.albionresearch.com/misc/urlencode.php -->
<a href="http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?name=Olli&
events.title=Strategy%20Meeting&
events.startTime=2014-02-01T10%3A00%3A00%2B01&
events.endTime=2014-02-01T11%3A30%3A00%2B01&
events.description=Discussion%20of%20the%20floreysoft%20strategy&
events.location=Telemannstra%C3%9Fe%2022%2C%2020255%20Hamburg&
events.title=Dinner&
events.startTime=2014-02-01T20%3A00%3A00%2B01&
events.endTime=2014-02-01T22%3A30%3A00%2B01&
events.description=Dinner%20with%20Le%20Chef&
events.location=Gau%C3%9Fstra%C3%9Fe%203%2C%2022765%20Hamburg
" target="_blank">Create and Download</a>

function postComplex() {
// to show that stringifying real dates does work as well
var date = new Date();
var events = {
name: "Olli",
events: [
{
title: "Strategy Meeting",
startTime: "Fri Feb 01 10:00:00 CET 2014",
endTime: "Fri Feb 01 11:30:00 CET 2014",
description: "Discussion of the floreysoft strategy",
location: "Telemannstraße 22, 20255 Hamburg"
}, {
title: "Dinner",
startTime: "Fri Feb 01 20:00:00 CET 2014",
endTime: date,
description: "Dinner with Le Chef",
location: "Gaußstraße 3, 22765 Hamburg"
}
]
};

var options = {
contentType: "application/json",
method : "post",
payload : Utilities.jsonStringify(events)
};

var response =
UrlFetchApp.fetch('http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?locale=DE',
options)
var blob = response.getBlob();
var code = response.getResponseCode();
Logger.log(code === 200 ? "Success" : "Error Code: " + code);

// sending out email just for demo purposes
// in real applications send out personalized emails using Ultradox instead
GmailApp.sendEmail("[your email goes here to send this to yourself]", "Your generated document",
"See attachment",
{ attachments: [
{ fileName: blob.getName(),
mimeType: "application/pdf",
content: blob.getBytes()
}
]
}
);
}

// this example requires GSON: http://code.google.com/p/google-gson/
URL url = new URL(
"http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?locale=DE");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("POST");
connection.setRequestProperty("Content-Type", "application/json");
connection.setDoInput(true);
connection.setDoOutput(true);

Events events = new Events("Olli");
events.addEvent(new Event("Strategy Meeting", new Date(113, 01, 01,
10, 00), new Date(113, 01, 01, 11, 30),
"Discussion of the floreysoft strategy",
"Telemannstraße 22, 20255 Hamburg"));
events.addEvent(new Event("Dinner", new Date(113, 01, 01,
20, 00), new Date(113, 01, 01, 22, 30),
"Dinner with Le Chef",
"Gaußstraße 3, 22765 Hamburg"));

// use ISO8601 date format for best compatibility
Gson gson = new GsonBuilder().setDateFormat("yyyy-MM-dd'T'HH:mm:ssX").create();
String json = gson.toJson(events);
byte[] bytes = json.getBytes("UTF-8"); // encoding is important when you are outside of ASCII
connection.setRequestProperty("Content-Length", Integer.toString(bytes.length));
OutputStream os = connection.getOutputStream();
os.write(bytes);
os.close();

InputStream inputStream = connection.getInputStream();
FileOutputStream outputStream = new FileOutputStream(new File("processed.pdf"));
transfer(inputStream, outputStream);

// this example requires GSON: http://code.google.com/p/google-gson/
URL url = new URL(
"http://www.ultradox.com/download/WNGkRelSf4oykbBWCsrNZ0yVVcAWPU?locale=DE");
URLFetchService urlFetchService = URLFetchServiceFactory.getURLFetchService();

Events events = new Events("Olli");
events.addEvent(new Event("Strategy Meeting", new Date(113, 01, 01,
10, 00), new Date(113, 01, 01, 11, 30),
"Discussion of the floreysoft strategy",
"Telemannstraße 22, 20255 Hamburg"));
events.addEvent(new Event("Dinner", new Date(113, 01, 01,
20, 00), new Date(113, 01, 01, 22, 30),
"Dinner with Le Chef",
"Gaußstraße 3, 22765 Hamburg"));

// use ISO8601 date format for best compatibility
Gson gson = new GsonBuilder().setDateFormat("yyyy-MM-dd'T'HH:mm:ssX").create();
String json = gson.toJson(events);

HTTPRequest request = new HTTPRequest(url, HTTPMethod.POST, FetchOptions.Builder.withDefaults().setDeadline(30.0));
request.setPayload(json.getBytes("UTF-8"));
request.setHeader(new HTTPHeader("Content-Type", "application/json"));

HTTPResponse response = urlFetchService.fetch(request);
byte[] content = response.getContent();

Complete examples on GitHub

Running asynchronously

When calling flows that may take longer than 60 seconds you will have to call them asynchronously.

Just replace the /run part of the URL with /runAsync to do so. Your call will immediately return and will trigger Ultradox as a long running task on the server.

You will not get the execution report as a result.

If you want to retrieve a document or any other information once the flow is completed, you will have to call your own app using a webhook and pass the desired information.

Standard parameters

You can append a number of standard parameters to your URL when invoking your automation. Make sure to encode the parameter values.

locale

Specifies the default locale that will be used to format dates, numbers and currencies.

Specify the locale by using the language code in ISO 639 and optionally by appending an underscore and the country code in ISO 3166 format.

Examples

en for English

en_US for English / US locale

en_GB for English / GB locale

de_DE for German locale

currency

Specifies the default currency code that will be used to format currencies.

Examples

USD for US Dollar

EUR for Euro

callback

Callback URL that will be called when your automation has finished.

It will either pass the defined output parameters in JSON format to the given URL or pass all available variables if no output parameters are defined.

cache

Specify a value for the cache parameter to cache the automation and all downloaded Google Docs. This can greatly improve the performance of your automation if you are calling the same automation multiple times.

To load a new version of your automation or the referenced Google Documents just send a different cache value.

Data types

When passing data using JSON or even in GET requests using URL parameters you need to know how to format them, so that Ultradox can make sense out of them.

Boolean

Booleans can be passed either with or without quotes.

If the value passed is the empty string or false, it is considered to be false. True in all other cases.

Number

Numbers are always specified as fixed point values. If the decimal point actually is . or rather a , depends on the specified locale.

String

Specify them encoded as UTF-8.

Date

Dates are the most complicated values to pass.

The format to be used in JSON is specified in ISO 8601.

If you use this format, you are on the safe side.

As a quick reference, a date formatted according to ISO 8601 might like that 2008-02-01T09:00:22+05:00.

Unfortunately, in some situations you are not free to choose formatting of dates.

These situations include using Google Apps Script or JSON libraries that do the formatting of dates for you.

To help you with that, Ultradox tries to accept and parse all standard input formats.

Let us know if there is a format Ultradox can not parse, but can be considered a standard by any means.

[a]Returned json data examples needs to be added.

- successful json data

- block execution failed json data

Explanation to what happens when credits run out. Will json be returned or will there be an specific http status code returned (with example).

[b]This part is been shown in the website: https://help.ultradox.com/en/guides/triggerultradox/viaapi.html

Questions and Feedback

If you have any comments on this page, feel free to add suggestions right to the Google document that we are using to create this site.

If you are not yet member of the Ultradox community on Google+, please join now to get updates from our end or to provide feedback, bug reports or discuss with other users.

Last Updated: 5/16/20