Skip to main content

REST input (Simple API)

The REST input connectors convert files sent in API requests. These connectors are also called the Conversion Service Simple API. Compared to the Advanced API, the Simple API returns converted files in just one API call.

REST input plain HTTP​

The REST Input connector sends files as single or multiple files in the request body. The connector then returns the response of whether the files were accepted or retrieves the result files.

Request​

The connector can handle the following two request formats:

  • Multiple files: Send as multipart/form-data body. All files are merged into the same job.
  • Single file: Send as a raw request body. Set the filename URL query parameter in the URL to specify the name of the file. Otherwise, a default name is used.

Options and variables​

Customize options and variables to either change the processing of the files in the workflow itself or in the output connector.

  • Options: Customize document processing with job and document options. Available options vary depending on the workflow you select. Options customize the processing of the documents in the workflow itself. For more information, see Job and document options documentation.
  • Variables: Use variables to pass through information to the output connector. The format of the variables is: [input:VARIABLE_NAME]. Use these variables, for example, in the output connectors such as:

Both Options and Variables support placeholder syntax. Conversion Service supports query parameters and form data extraction. Query parameters are supported with the placeholder syntax for both request formats. Note that the form request format is not available for the single file:

  • [query:QUERY-PARAM-NAME, 'DEFAULT-VALUE']
  • [form:FORM-DATA-NAME, 'DEFAULT-VALUE']
Configuration window of REST Input (HTTP Plain).

Response​

The connector can be configured to provide one of the following three different response types:

  • The call returns with an HTTP status 202 Accepted immediately. The result is handled exclusively by the configured output connectors.
  • The call blocks until the job has finished and the first result file is returned as response body.
  • The call blocks until the job has finished and all result files are returned as multipart/form-data response.

REST input JSON​

The REST Input connector uses JSON as a structured format for request and response.

Request​

This connector allows to specify a job in a structured format (JSON). The files to be converted can either be referenced by URL or included directly in the job description.

{
  "name": "JOB_NAME",
  "options": [
    { "name": "OPTION_NAME", "value": "OPTION_VALUE" }
  ],
  "variables": {
    "VARIABLE_NAME": "VARIABLE_VALUE"
  },
  "data": [
    // First file referenced by URL
    { "url": "http://example.com/path/to/file.jpg" },
    // Second file inline
    { "fileName": "file.jpg", "content": "BASE64_ENCODED_FILE" },
    // Third file with options
    { "fileName": "file2.jpg", "content": "BASE64_ENCODED_FILE",
      "options": [ { "name": "DOC.PASSWORD", "value": "USE_YOUR_PASSWORD" } ] }
  ]
}

Options and variables​

Customize options and variables to either change the processing of the files in the workflow itself or in the output connector.

  • Options: Customize document processing with job and document options. Available options vary depending on the workflow you select. Options customize the processing of the documents in the workflow itself. For more information, see Job and document options documentation.
  • Variables: Use variables to pass through information to the output connector. The format of the variables is: [input:‹variable name›]. Use these variables, for example, in the output connectors such as:

Response​

The connector can be configured to provide one of the following two different response types:

  • The call returns with an HTTP status 202 Accepted immediately. The result is handled exclusively by the configured output connectors.
  • The call blocks until the job has finished and all result files are returned as a structured JSON response.
{
  "data": [
    { "fileName": "file.pdf", "content": "BASE64_ENCODED_FILE" },
    { "fileName": "report.txt", "content": "BASE64_ENCODED_FILE" }
  ]
}