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 happend 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.