Skip to main content

Postman Collection

To test our API without writing a single line of code, we used our OpenAPI Specification to generate a dedicated Postman Collection.

Postman is an API Platform for building and using APIs. Postman Collections can describe all the methods exposed by an API, making it possible for the user to modify the different request parameters and perform actual calls towards the API, obtaining the HTTP response as a result.

0️⃣  Install Postman

To use our collection, we suggest downloading Postman on your device; it is available for Windows, Mac, and Linux.

Next, sign up to Postman: don't worry, to use our collection the Free Plan is enough 😉

1️⃣  Import the Collection

Our Collection is generated automatically using our OpenAPI Specification, and can be downloaded from our GitHub Repository at the postman/fic-api.json position; it is updated every time a new version of the Specification is released, so you can just redownload it to keep in sync.

Once you downloaded the JSON file of the collection, you can import it following this procedure.

Now you're almost ready to interact with our API!

Not satisfied by our collection?

If you prefer, you can instead use our OpenAPI Specification directly, importing the openapi.yaml file using this procedure. You just need to be sure to download also the files in the models folder, otherwise, the import will fail. Also, you need to select the right parameters to import the collection correctly.

2️⃣  Authorization

Next, to be able to interact with our API you need to be authorized: see the Authentication page for further info.

You have two main options to retrieve a valid token:

  1. Manual Authentication: since Postman is mainly used to test and discover our API behavior, this is a great use case for Manual Authentication. Just generate a new token with the required scopes and insert it in Postman!
  2. OAuth 2.0 Authorization Code: if you want to test the authentication step, you can try to retrieve the token and insert it in Postman.

Once you retrieved a valid token, you can just insert it as a Bearer token following this procedure.

If you want, you can also use Postman to retrieve your Access Token automatically from its interface. To set it up, click on the collection and select the Authorization tab, then compile the Configure New Token form.

Configure New Token Form Configure New Token Form

The parameters are:

  1. Auth URL:
  2. Access Token URL:
  3. Callback URL: The redirect URL declared for the OAuth2 Application

All the other parameters can be found on the OAuth 2.0 Authentication Code Flow page.

3️⃣  Test our APIs!

You're finally ready to test our API using Postman. Select the method you want to try, compile the request parameters and click the Send button! Have fun!

Retrieve your Company ID!

Many of our methods are Company-scoped, which means they require to indicate the ID of the Company we're operating on.
The good news is that you can use Postman to retrieve it! Check the Company-scoped Methods page for more info!

📚  Additional resources