Making your first API v3 call with POSTMAN

You can download our Postman collection here.
Postman allows you to easily test all the API endpoints without developing and coding.

In this tutorial, we will cover:

JWT introduction, definition
Generation of your own token
Setting up the Postman app
Input the JWT token to the Postman app
Create a template using Postman - your first API call
Merge a template with your JSON data using Postman

JWT introduction, definition

JSON Web Tokens are composed of three sections: a header, a payload (containing a claim set), and a signature. The header and payload are JSON objects, which are serialized to UTF-8 bytes, then encoded using base64url encoding.

The JWT's header, payload, and signature are concatenated with periods (.). As a result, a JWT typically takes the following form:

{Base64url encoded header}.{Base64url encoded payload}.{Base64url encoded signature}

Generation of your own token

Header

Property alg defines which signing algorithm is being used. PDF Generator API users HS256. Property typ defines the type of token and it is always JWT.

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload

The second part of the token is the payload, which contains the claims or the pieces of information being passed about the user and any metadata required. It is mandatory to specify the following claims:

issuer (iss): Your API key
subject (sub): Workspace identifier
You can also specify the token expiration time (exp) which is timestamp in seconds since Epoch (unix epoch time). It is highly recommended to set the exp timestamp for a short period, i.e. a matter of seconds. This way, if a token is intercepted or shared, the token will only be valid for a short period of time.

{
  "iss": "ad54aaff89ffdfeff178bb8a8f359b29fcb20edb56250b9f584aa2cb0162ed4a",
  "sub": "demo.example@actualreports.com",
  "exp": 1586112639
}

Signature

To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that. The signature is used to verify the message wasn't changed along the way, and, in the case of tokens signed with a private key, it can also verify that the sender of the JWT is who it says it is.

HMACSHA256(
    base64UrlEncode(header) + "." +
    base64UrlEncode(payload),
    API_SECRET)

Putting all together

The output is three Base64-URL strings separated by dots. The following shows a JWT that has the previous header and payload encoded, and it is signed with a secret.

In the jwt.io it should looks like this:


In case you would like to learn more about the background of the JWT or get more inputs how you can use it - jwt.io website here

You can create a temporary token on the Settings page after you login to PDF Generator API. The generated token uses your email address as the subject (sub) value and is valid for 15 minutes. These test tokens should never be used in production applications.

Setting up the Postman App

You can download Postman collection for PDF Generator API here.
After the import, in the left sidebar, you should be able to see the list of 11 different requests, copying the logic in our API documentantion

Input the JWT token to the Postman app

JWT token import

Create a template using Postman - your first API call

After the request is send, the template of your ID is returned back via the JSON file. Hooray, your first successful API call!

Create Template

Merge a template with your JSON data using Postman

Merges template with data and returns a public URL to a document. You should send the JSON encoded data in request body as the data parameter. After the request is send, the URL for the generated document is returned. You can read more about all the parameters in our API documentantion.

Create Template

Updated on: 08/09/2023