Getting Started

Getting Started explains how to use the Postman application to call an Acquisio API.

Provisioning API is used as an example in this guide. The explanations about how to use another API will be provided at the end of this guide.

If you have any question, you can send an email to api@acquisio.com.

Postman

The steps in this guide require Postman version 5.4.1 or greater. Since the Chrome app of Postman is deprecated and hasn’t been updated recently, the desktop application of Postman must be used instead.

curl and other tools

If you prefer to use the curl command-line tool, see Getting Started with curl.

If you want to use another desktop application, you can refer to Getting Started - Manual Setup. The Manual Setup should be easier to adapt for another application, since it explains how to manually retrieve OAuth access tokens instead of using Postman OAuth support.

Importing an OpenAPI/Swagger file as a Postman collection

All the Acquisio APIs are documented with an OpenAPI/Swagger file. Postman is able to import that file and generate a collection for the API.

• Open Postman.
• Click on the Import button

• In the new window that appears, select Import From Link.
• Paste the following link: https://api.acquisio.com/specs/provisioning-api-v0.yaml
• Click on Import

A Postman collection for the Provisioning API will appear in the Collections section.

Managing the OAuth 2 access tokens

The Acquisio APIs are secured with OAuth 2.0. A clientId and a clientSecret have been communicated to you by Acquisio. They can be used to retrieve an access token that will grant access to the Acquisio APIs for a limited amount of time.

Postman can be configured to manage the access tokens for all the requests of the Provisioning API collection.

• Right-click on the Provisioning API collection you created previously and select Edit
• Select Authorization
• Set the Type to OAuth 2.0 in the dropdown list
• Click on Get New Access Token

In the new window that appears:

• Choose a Token Name. It can be the name of your organization in the Acquisio platform.
• Set the Grant Type to Client Credentials
• Set the Access Token URL to https://api.acquisio.com/token
• Set the Client ID and Client Secret to the values that were provided to you by Acquisio
• Set the Client Authentication to Send client credentials in body
• Click on Request Token

A window will appear to show the access token that was retrieved. Click on Use Token.

In the Edit collection window, click on Update to save the changes to the Postman collection.

Calling an API endpoint

In the Collections section, click on the folder named adplatform-master-accounts.

Open the request named GET Retrieve a list of Ad Platform master accounts.

By default, the URL has placeholders for the query parameters that can be used with this endpoint: ?limit={{limit}}&offset={{offset}}&id={{id}}. Remove them to have the following URL: https://api.acquisio.com/provisioning/v0/adplatform-master-accounts

Under Authorization, the Type is set to Inherit auth from parent. It means that the request is configured to use the access token of the Postman collection.

Click on the blue Send button to sent the request.

Under the Body tab, a JSON response will display the master accounts that are available in your Acquisio organization.

{
  "adPlatformMasterAccounts": [
    {
      "adPlatformType": "GoogleAds",
      "id": 5735,
      "name": "Google Ads Master Account (MCC)",
      "status": "Active",
      "linkedAdPlatformAccounts": [
        {
          "id": 6134534,
          "name": "Google Ads Account",
          "adPlatformId": 4539460766,
          "status": "ReadWrite",
          "currency": "CAD",
          "timeZone": "America/Toronto",
          "adPlatformType": "GoogleAds"
        }
      ],
      "adPlatformId": 4560348958
    }
  ]
}

Under the Headers tab, additional information will be available.

...
X-UniqueCallId → 91c15212-d358-4c07-a855-f05b71ed80f9
X-TotalCount → 1

Expiration of the access token

After some time, the OAuth access token will expire and the response of your requests will have the status 401 Unauthorized. When that happens, you need to right-click on the Provisioning API collection and select Edit. Then go to Authorization and click on Get New Access Token to retrieve a new access token.

Importing other APIs in Postman

The page APIs list all the Acquisio APIs. Each API has its own reference page (ex: Provisioning API v0). There’s a Download button on the reference page that allows to download the OpenAPI specification of an API. The OpenAPI file can then be imported in Postman.

Encoding URL reserved characters

URL reserved characters must be encoded. For example, a request with the following query parameter filter=statistics.clicks:[1 TO *] needs to be encoded as filter=statistics.clicks%3A%5B1%20TO%20*%5D. Otherwise, a 400 error will be returned by the API.

This can be done in Postman by clicking on the Params button to open a grid with the query parameters. Right-click on the query parameter value to encode, then select in the menu “EncodeURIComponent”. EncodeURIComponent will convert a value like filter=statistics.clicks:[1 TO *] to filter=statistics.clicks%3A%5B1%20TO%20*%5D. DecodeURIComponent can be used to convert from filter=statistics.clicks%3A%5B1%20TO%20*%5D to filter=statistics.clicks:[1 TO *].

For more information about encoding in Postman, refer to the Postman official documentation.