Provisioning API (v0)

Download OpenAPI specification: Download

Contact: api@acquisio.com

The Provisioning API is a RESTful API using Swagger contracts to allow authenticated consumers of the API to create and update entities in Acquisio and supported Ad Platforms.

Ad Platforms

The Provisioning API supports 3 Ad Platforms: Google Ads, Microsoft Advertising and Facebook.

Acquisio uses the term ‘Ad Platform account’ to refer to a child account at one of these supported Ad Platforms. An ‘Ad Platform master account’ refers to a parent account that can contain multiple Ad Platform accounts. ‘Acquisio Organization’ is an Acquisio concept. Ad Platform master accounts are linked to an Acquisio Organization. The Provisioning API currently supports Ad Platform master accounts for Google Ads and Microsoft Advertising.

For Google Ads, an Ad Platform master account is setup by linking a manager account (formerly known as MCC) in Acquisio.

For Microsoft Advertising, an Ad Platform master account is setup by linking a Microsoft Advertising reseller account in Acquisio. The Microsoft Advertising reseller account can be setup through the Microsoft Advertising Partners Program.

Note: An Acquisio account can contain multiple Ad Platform accounts and campaigns.

Provisioning

The Acquisio Provisioning API provides a straightforward way to programmatically setup an Acquisio account to make it easy for a campaign manager to start managing campaigns. Endpoints provide a way to:

  • Create and update an Acquisio account
  • Link and manage an existing Ad Platform account
  • Create a new Ad Platform account in an Ad Platform master account
  • Import existing campaigns from an Ad Platform account
  • Initiate the Power-Cloner to copy campaigns from Google Ads to Microsoft Advertising

Labels

Labels can be used to store information on an account or a campaign. Each label has a name and a value.

For example, on an account, a label named City can be set with the value Hollywood. Another label named Continent can be added with North America as its value. Those labels allow to know the city of each account or to retrieve a list of accounts for a specific city.

It's also possible to store external unique identifiers in a label, like a label named clientId that stores the ID of the client from an external system.

For more information about labels, refer to the labels endpoints.

The labels set with Provisioning API can also be retrieved with Reporting API.

Versioning

All Acquisio APIs are versioned the same way. For more information, refer to Versioning.

Backward-compatible changes are documented in the Provisioning API v0 Release Notes.

Security

The Provisioning API is secured with OAuth 2.0. For more information about the security, see Getting Started.

Each set of OAuth 2.0 credentials grant access to one Acquisio Organization.

OAuth 2.0 Grant TypeSwagger OAuth FlowToken URL
Client Credentialsapplicationhttps://api.acquisio.com/token

Errors

HTTP 400 (Bad Request) errors are presented for each endpoint if appropriate.

Some endpoints that offer bulk operations have partial errors. They return a successful HTTP status (like 200), but the response body includes a list of errors for the operations that failed. Example: Clone-sync campaigns.

Many HTTP status (like 403 or 500) are used the same way in all Acquisio APIs. For a complete list, please consult Error Codes.

Accounts

An Acquisio account exists in an Acquisio Organization. The Acquisio Organization is the container of Acquisio accounts. An Acquisio account is the container of Ad Platform accounts. Multiple Ad Platform accounts can be created or linked inside an Acquisio account.

Note: Typically, there is one Acquisio account for each advertiser.

Hierarchy

Parents: None.

Children: Ad Platform Account.

Statistics

Accounts have statistics that can be retrieved with the Reporting API.

Language and Country

In order to create an account, you need to provide both a combination of a languageCode and a countryCode.

The table below provides a list of the supported languageCode and countryCode combinations.

LanguageLanguage codeCountryCountry code
ChinesezhChinaCN
ChinesezhHong KongHK
ChinesezhSingaporeSG
ChinesezhTaiwanTW
DanishdaDenmarkDK
DutchnlBelgiumBE
DutchnlNetherlandsNL
EnglishenAustraliaAU
EnglishenCanadaCA
EnglishenDenmarkDK
EnglishenIndonesiaID
EnglishenIrelandIE
EnglishenNew ZealandNZ
EnglishenSouth AfricaZA
EnglishenUnited KingdomGB
EnglishenUnited StatesUS
FinishfiFinlandFI
FrenchfrBelgiumBE
FrenchfrCanadaCA
FrenchfrFranceFR
FrenchfrSwitzerlandCH
FrenchfrUnited StatesUS
GermandeAustriaAT
GermandeGermanyDE
GermandeSwitzerlandCH
ItalianitItalyIT
JapanesejaJapanJP
Norwegian BokmalnbNorwayNO
PortugeseptBrazilBR
SpanishesArgentinaAR
SpanishesMexicoMX
SpanishesSpainES
SpanishesUnited StatesUS
SwedishsvFinlandFI
SwedishsvSwedenSE

Create a new account

Creates a new Acquisio account. Labels can be set during the creation of an account and are optional.

Note: Setting autoImport to true at the account level, will automatically import all campaigns from each Ad Platform account that is linked to the Acquisio account. This includes Ad Platform accounts that are linked manually via the Acquisio UI.

Request Body

Account resource to create.


account
AccountCreateUpdate
name
string Required

Name of the account.

languageCode
string Required

Language code of two letters. The available languages depend on the country.

Available language-country combinations.

countryCode
string Required

Country code of two letters. The country determines which languages are available.

Available language-country combinations.

currency
string Required

The currency code determines in which currency the monetary statistics (ex: cost) will be displayed in Client Campaigns. If two currencies like USD and CAD are both used in a single account, the currency code will be used to convert the amounts to a single currency for display purposes.

List of the allowed ISO 4217 currency codes.

notes
string

Notes related to the account.

autoImport
boolean

If autoImport is set to true, all campaigns that are not already imported in the linked Ad Platform accounts of this Acquisio account will be automatically imported.

field1
string
field2
string
field3
string
field4
string
field5
string
field6
string
field7
string
field8
string
field9
string
field10
string
field11
string
field12
string
field13
string
field14
string
field15
string
field16
string
field17
string
field18
string
field19
string
field20
string
field21
number <double>
field22
number <double>
field23
number <double>
field24
number <double>
field25
number <double>
field26
number <double>
field27
number <double>
field28
number <double>
field29
number <double>
field30
number <double>
labels
Label

Responses

201 Creation of a single account was successful.

Response Schema

400 Bad request

Response Schema
post
/accounts

Server URL

https://api.acquisio.com/provisioning/v0/accounts
Request samples
{
  • "account":
    {
    }
}

Response samples
  • 201 Creation of a single account was successful.

  • 400 Bad request

{
  • "account":
    {
    }
}
{
  • "error":
    {
    }
}

Retrieve a list of accounts

Retrieves a list of accounts with its linked Ad Platform accounts.

Parameters
query Parameters ?
limit
integer <int64>

Size of the page that will be returned in the response.

  • The maximum allowed value is 100.
  • The default value is 100.
offset
integer <int64>

Zero-based index of the first resource that will be returned in the response.

  • The default value is 0 (the first resource).
  • The resource is sorted by default in ascendant order by its id attribute to keep the pages consistent between requests.
  • Offset values can only be 0 or a multiple of the limit parameter.
labels
Comma Separated string

List of filters on labels. Only resources that match all the filters are returned.

Labels are defined by labelName:labelValue (Example: department:clothing,city:Montreal means that only accounts from the department clothing and from the city of Montreal will be returned.) This format is subject to change in later versions.

  • The maximum filters on labels is 5.
id
Comma Separated integer <int64>

List of account IDs separated by a comma. If id is omitted, all available accounts are returned. If id is provided, only the accounts included in id will be returned.

Responses

200 Listed accounts successfully

Headers
X-TotalCount
number <int64>

Count of total available resources.

Response Schema

400 Bad request

Response Schema
get
/accounts

Server URL

https://api.acquisio.com/provisioning/v0/accounts

Response samples
  • 200 Listed accounts successfully

  • 400 Bad request

{
  • "accounts":
    [
    ]
}
{
  • "error":
    {
    }
}

Retrieve a single account

Retrieve a single account with its linked Ad Platform accounts.

Parameters
path Parameters ?
id
integer <int64> Required

ID of the account.

Responses

200 Get single account successfully

Response Schema

400 Bad request

Response Schema

404 Not found

Response Schema
get
/accounts/id/{id}

Server URL

https://api.acquisio.com/provisioning/v0/accounts/id/{id}

Response samples
  • 200 Get single account successfully

  • 400 Bad request

  • 404 Not found

{
  • "account":
    {
    }
}
{
  • "error":
    {
    }
}
{
  • "error":
    {
    }
}

Overwrite an account

Updates all fields of a single account based on the ID provided to the endpoint.

Note: This should be implemented with caution since fields missing from the request will be overwritten with null values in the database even if they had previous values. For labels, any past labels will be overwritten by the labels field in the request payload.

Parameters
path Parameters ?
id
integer <int64> Required

ID of the account.

Request Body

Account object with all of its fields.


account
AccountCreateUpdate
name
string Required

Name of the account.

languageCode
string Required

Language code of two letters. The available languages depend on the country.

Available language-country combinations.

countryCode
string Required

Country code of two letters. The country determines which languages are available.

Available language-country combinations.

currency
string Required

The currency code determines in which currency the monetary statistics (ex: cost) will be displayed in Client Campaigns. If two currencies like USD and CAD are both used in a single account, the currency code will be used to convert the amounts to a single currency for display purposes.

List of the allowed ISO 4217 currency codes.

notes
string

Notes related to the account.

autoImport
boolean

If autoImport is set to true, all campaigns that are not already imported in the linked Ad Platform accounts of this Acquisio account will be automatically imported.

field1
string
field2
string
field3
string
field4
string
field5
string
field6
string
field7
string
field8
string
field9
string
field10
string
field11
string
field12
string
field13
string
field14
string
field15
string
field16
string
field17
string
field18
string
field19
string
field20
string
field21
number <double>
field22
number <double>
field23
number <double>
field24
number <double>
field25
number <double>
field26
number <double>
field27
number <double>
field28
number <double>
field29
number <double>
field30
number <double>
labels
Label

Responses

200 Updated account successfully.

Response Schema

400 Bad request

Response Schema

404 Not found

Response Schema
put
/accounts/id/{id}

Server URL

https://api.acquisio.com/provisioning/v0/accounts/id/{id}
Request samples
{
  • "account":
    {
    }
}

Response samples
  • 200 Updated account successfully.

  • 400 Bad request

  • 404 Not found

{
  • "account":
    {
    }
}
{
  • "error":
    {
    }
}
{
  • "error":
    {
    }
}

Update an account (specific fields)

Updates only specified fields of a single account based on the ID in the endpoint. The update uses the Json Merge Patch format. For labels, if the labels field is present in the request, any past labels will be overwritten by the labels field in the request payload.

Parameters
path Parameters ?
id
integer <int64> Required

ID of the account.

Request Body

Account object with the fields to update.


account
AccountCreateUpdate
name
string Required

Name of the account.

languageCode
string Required

Language code of two letters. The available languages depend on the country.

Available language-country combinations.

countryCode
string Required

Country code of two letters. The country determines which languages are available.

Available language-country combinations.

currency
string Required

The currency code determines in which currency the monetary statistics (ex: cost) will be displayed in Client Campaigns. If two currencies like USD and CAD are both used in a single account, the currency code will be used to convert the amounts to a single currency for display purposes.

List of the allowed ISO 4217 currency codes.

notes
string

Notes related to the account.

autoImport
boolean

If autoImport is set to true, all campaigns that are not already imported in the linked Ad Platform accounts of this Acquisio account will be automatically imported.

field1
string
field2
string
field3
string
field4
string
field5
string
field6
string
field7
string
field8
string
field9
string
field10
string
field11
string
field12
string
field13
string
field14
string
field15
string
field16
string
field17
string
field18
string
field19
string
field20
string
field21
number <double>
field22
number <double>
field23
number <double>
field24
number <double>
field25
number <double>
field26
number <double>
field27
number <double>
field28
number <double>
field29
number <double>
field30
number <double>
labels
Label

Responses

200 Partly updated account successfully.

Response Schema

400 Bad request

Response Schema

404 Not found

Response Schema
patch
/accounts/id/{id}

Server URL

https://api.acquisio.com/provisioning/v0/accounts/id/{id}
Request samples
{
  • "account":
    {
    }
}

Response samples
  • 200 Partly updated account successfully.

  • 400 Bad request

  • 404 Not found

{
  • "account":
    {
    }
}
{
  • "error":
    {
    }
}
{
  • "error":
    {
    }
}

Ad Platform Master Accounts

This endpoint can be used to interact with the Ad Platform master accounts that are linked to an Acquisio Organization.

Note: Ad Platform master accounts can only be created by linking Google Ads master accounts and/or Microsoft Advertising Reseller accounts to an Acquisio organization via the Acquisio UI.

Hierarchy

Parents: None.

Children: Ad Platform Account (for Ad Platform accounts that are associated to an Ad Platform master account).

Ad Platform Master Reseller Accounts

Organizations who are partnered with Microsoft Advertising through the Microsoft Advertising Partners Program will have a Microsoft Advertising Reseller account.

This endpoint can be used to interact with the Ad Platform master reseller accounts that are linked to an Acquisio Organization

Note: Ad Platform Master accounts can only be created by linking Microsoft Advertising Reseller accounts to an Acquisio organization via the Acquisio UI.

Hierarchy

Parents: None.

Children: None.

Ad Platform Accounts

Ad campaigns and their child entities are created in an Ad Platform account. Ad Platform accounts can be linked to an Acquisio account in 2 ways:

  • By linking an existing Ad Platform account to an Acquisio account
  • By creating a new Ad Platform account associated to an Acquisio account

This establishes a connection between Acquisio and the Ad Platform so that assets at the Ad Platform (like campaigns) can be retrieved in order to import them in the Acquisio platform.

Endpoints within this section enable Ad Platform accounts to be linked, created, modified or deleted within an Acquisio account.

Note:

  • Ad Platform accounts can also be linked to an Acquisio account via the Acquisio UI
  • A single Acquisio account can be linked to multiple Ad Platform accounts
  • It is technically possible to link a single Ad Platform account to multiple Acquisio accounts

Hierarchy

Parents: Account, Ad Platform Master Account (if the Ad Platform account is associated to an Ad Platform master account).

Children: Campaign.

Statistics

Ad Platform accounts have statistics that can be retrieved with the Reporting API.

Campaigns

Endpoints in this section allow Ad Platform campaigns to be imported to an Acquisio account and to have a list of previously imported campaigns.

Importing campaigns to Acquisio

Importing campaigns to an Acquisio account is required to be able to report on performance and manage the campaigns. Campaigns have many child entities including Ad Groups, Keywords and Ads. When a campaign is imported, all its child entities are also imported. When a campaign is imported, it becomes visible in the Acquisio UI and any changes made to the campaign or its child entities via the Acquisio UI are pushed to the Ad Platform.

There are two ways to import campaigns into Acquisio:

  • Import a specific campaign contained in a linked Ad Platform account to an Acquisio account
  • Automatically import all campaigns from a linked Ad Platform account to an Acquisio account. This includes new campaigns that are created directly in the Ad Platform.

Note: To automatically import all campaigns from linked Ad Platform accounts, the autoImport field of the account must be set to "true".

Hierarchy

Parents: Ad Platform Account.

Children: A campaign has various children (like Ad Groups, Keywords and Ads) which are not available through the Provisioning API.

Statistics

The statistics of Campaigns, Ad Groups, Keywords and Ads can be retrieved with the Reporting API.

Campaign Group

acquisio:campaignGroup is a special system label that associates campaigns in groups. When a campaign is imported to the Acquisio platform, a campaign group must be provided. The campaign groups are visible in the Workbench of Client Campaigns.

acquisio:campaignGroup isn't supported yet by the endpoints dedicated to the labels, it can only be used when importing campaigns.

Power Cloner

Labels

Jobs

Some endpoints in the Provisioning API create an asynchronous job to execute the operation that was requested. Endpoints in this section provide a way to retrieve information about jobs initiated in the last seven days.