How to get started with the 4-Heights® Conversion Service using Postman

Postman is a free-to-download tool for making HTTP requests. It can be used for testing and getting acquainted with any REST API such as the one offered by the 4-Heights® Conversion Service.

Set up the system

1. Download and install the 4-Heights® Conversion Service.

2. Download and install Postman.

3. Import request collection to Postman

  • Download collection: Postman Collection
  • Open Postman and click Import.
  • Drag downloaded collection to import window.
  • Click on 4-Heights® Conversion Service in the Collections view.

Try it out

1. First, ensure the baseURL in your collection variables specifies the host where your 4-Heights® Conversion Service runs.

2. Have a look at the available requests: API Reference

3. To get acquainted with Postman, try out a simple request: list available workflows.

  • This is useful for gaining an overview of the available workflows.
  • The name of a workflow can then be used as an input parameter when creating a new job.

4. Process your first file (for more information about the job processing sequence, please refer to the section "API Usage" in the Manual)

  • Create new job with a workflow of your choice.
    • The job is created and ready for data.
    • The id of the newly created job is saved in the collection variable jobId and used automatically for subsequent requests.
  • Get job info to verify that a job was actually created.
    • The response should tell you that the status of the job is "created".
  • Add data to job (choose file in Body tab).
    • You can repeat this step several times with different files in order to add more data to your job.
  • Start job
    • The conversion service will start processing all the documents you added to the job.
  • Get job info again.
    • The response should now tell you that the status of the job is "completed" (or "processing" if you added large files and it has not finished yet).
  • Get job result to receive information about the result (like events that happened during conversion).
    • The id of the first result data set is stored in the collection variable resultId and used automatically in the subsequent request.
    • If your workflow returns more than one result data set, copy all ids.
  • Get job result data to receive the actual document generated by the conversion service.
    • Save the response as a PDF file to view it (click on Save Response, then Save to a file on the right hand side).
  • Delete job to free up any resources used for processing it.
    • All collection variables associated with the job are reset.