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 selectEdit
- Select
Authorization
- Set the
Type
toOAuth 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
toClient Credentials
- Set the
Access Token URL
to https://api.acquisio.com/token - Set the
Client ID
andClient Secret
to the values that were provided to you by Acquisio - Set the
Client Authentication
toSend 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.