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.
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.
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:
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.
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.
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 Type | Swagger OAuth Flow | Token URL |
---|---|---|
Client Credentials | application | https://api.acquisio.com/token |
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.
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. Parents: None. Children: Ad Platform Account. Accounts have statistics that can be retrieved with the Reporting API. In order to create an account, you need to provide both a combination of a The table below provides a list of the supported languageCode and countryCode combinations.Hierarchy
Statistics
Language and Country
languageCode
and a countryCode
.
Language Language code Country Country code Chinese zh China CN Chinese zh Hong Kong HK Chinese zh Singapore SG Chinese zh Taiwan TW Danish da Denmark DK Dutch nl Belgium BE Dutch nl Netherlands NL English en Australia AU English en Canada CA English en Denmark DK English en Indonesia ID English en Ireland IE English en New Zealand NZ English en South Africa ZA English en United Kingdom GB English en United States US Finish fi Finland FI French fr Belgium BE French fr Canada CA French fr France FR French fr Switzerland CH French fr United States US German de Austria AT German de Germany DE German de Switzerland CH Italian it Italy IT Japanese ja Japan JP Norwegian Bokmal nb Norway NO Portugese pt Brazil BR Spanish es Argentina AR Spanish es Mexico MX Spanish es Spain ES Spanish es United States US Swedish sv Finland FI Swedish sv Sweden SE
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.
Account resource to create.
account null |
AccountCreateUpdate
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
201 Creation of a single account was successful.
400 Bad request
{}
"account": {}
"name": "Construction Inc.", "languageCode": "en", "countryCode": "CA", "currency": "CAD", "notes": "This account is for the reporting needs of our construction project in Denver.", "autoImport": false, "field1": "Construction Inc.", "field2": "Annual reporting", "field3": "Spendings", "field4": "Reports", "field5": "Contractors", "field6": "Employees", "field7": "string", "field8": "string", "field9": "555-555-5555", "field10": "California", "field11": "USA", "field12": "Loans", "field13": "Budget", "field14": "string", "field15": "string", "field16": "string", "field17": "string", "field18": "string", "field19": "string", "field20": "string", "field21": 27, "field22": 34.09, "field23": 2, "field24": 8, "field25": 1, "field26": 1, "field27": 500, "field28": 2.91, "field29": 0, "field30": 0, "labels": []
{}
"name": "City", "value": "Los Angeles"
201 Creation of a single account was successful.
400 Bad request
{}
"account": {}
"name": "Construction Inc.", "languageCode": "en", "countryCode": "CA", "currency": "CAD", "notes": "This account is for the reporting needs of our construction project in Denver.", "autoImport": false, "field1": "Construction Inc.", "field2": "Annual reporting", "field3": "Spendings", "field4": "Reports", "field5": "Contractors", "field6": "Employees", "field7": "string", "field8": "string", "field9": "555-555-5555", "field10": "California", "field11": "USA", "field12": "Loans", "field13": "Budget", "field14": "string", "field15": "string", "field16": "string", "field17": "string", "field18": "string", "field19": "string", "field20": "string", "field21": 27, "field22": 34.09, "field23": 2, "field24": 8, "field25": 1, "field26": 1, "field27": 500, "field28": 2.91, "field29": 0, "field30": 0, "labels": [],
{}
"name": "City", "value": "Los Angeles" "id": 738, "linkedAdPlatformAccounts": []
{}
"type": "string", "id": 0, "name": "Google Ads - Construction Inc.", "status": "ReadWrite", "adPlatformId": "444-444-4445", "accountId": 123, "currency": "CAD", "adPlatformType": "GoogleAds", "isLoginValid": true
{}
"error": {}
"message": "Field fieldThatIsWrong doesn't exist.", "status": 400, "internalErrorId": "37eae2d9-65bf-4360-8950-450e1bd61dc0", "errors": []
{}
"message": "Field fieldThatIsWrong doesn't exist."
Retrieves a list of accounts with its linked Ad Platform accounts.
Size of the page that will be returned in the response.
Zero-based index of the first resource that will be returned in the response.
id
attribute
to keep the pages consistent between requests.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.
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.
200 Listed accounts successfully
Count of total available resources.
400 Bad request
200 Listed accounts successfully
400 Bad request
{}
"accounts": []
{}
"name": "Construction Inc.", "languageCode": "en", "countryCode": "CA", "currency": "CAD", "notes": "This account is for the reporting needs of our construction project in Denver.", "autoImport": false, "field1": "Construction Inc.", "field2": "Annual reporting", "field3": "Spendings", "field4": "Reports", "field5": "Contractors", "field6": "Employees", "field7": "string", "field8": "string", "field9": "555-555-5555", "field10": "California", "field11": "USA", "field12": "Loans", "field13": "Budget", "field14": "string", "field15": "string", "field16": "string", "field17": "string", "field18": "string", "field19": "string", "field20": "string", "field21": 27, "field22": 34.09, "field23": 2, "field24": 8, "field25": 1, "field26": 1, "field27": 500, "field28": 2.91, "field29": 0, "field30": 0, "labels": [],
{}
"name": "City", "value": "Los Angeles" "id": 738, "linkedAdPlatformAccounts": []
{}
"type": "string", "id": 0, "name": "Google Ads - Construction Inc.", "status": "ReadWrite", "adPlatformId": "444-444-4445", "accountId": 123, "currency": "CAD", "adPlatformType": "GoogleAds", "isLoginValid": true
{}
"error": {}
"message": "Field fieldThatIsWrong doesn't exist.", "status": 400, "internalErrorId": "37eae2d9-65bf-4360-8950-450e1bd61dc0", "errors": []
{}
"message": "Field fieldThatIsWrong doesn't exist."
Retrieve a single account with its linked Ad Platform accounts.
ID of the account.
200 Get single account successfully
400 Bad request
404 Not found
200 Get single account successfully
400 Bad request
404 Not found
{}
"account": {}
"name": "Construction Inc.", "languageCode": "en", "countryCode": "CA", "currency": "CAD", "notes": "This account is for the reporting needs of our construction project in Denver.", "autoImport": false, "field1": "Construction Inc.", "field2": "Annual reporting", "field3": "Spendings", "field4": "Reports", "field5": "Contractors", "field6": "Employees", "field7": "string", "field8": "string", "field9": "555-555-5555", "field10": "California", "field11": "USA", "field12": "Loans", "field13": "Budget", "field14": "string", "field15": "string", "field16": "string", "field17": "string", "field18": "string", "field19": "string", "field20": "string", "field21": 27, "field22": 34.09, "field23": 2, "field24": 8, "field25": 1, "field26": 1, "field27": 500, "field28": 2.91, "field29": 0, "field30": 0, "labels": [],
{}
"name": "City", "value": "Los Angeles" "id": 738, "linkedAdPlatformAccounts": []
{}
"type": "string", "id": 0, "name": "Google Ads - Construction Inc.", "status": "ReadWrite", "adPlatformId": "444-444-4445", "accountId": 123, "currency": "CAD", "adPlatformType": "GoogleAds", "isLoginValid": true
{}
"error": {}
"message": "Field fieldThatIsWrong doesn't exist.", "status": 400, "internalErrorId": "37eae2d9-65bf-4360-8950-450e1bd61dc0", "errors": []
{}
"message": "Field fieldThatIsWrong doesn't exist."
{}
"error": {}
"message": "Field fieldThatIsWrong doesn't exist.", "status": 400, "internalErrorId": "37eae2d9-65bf-4360-8950-450e1bd61dc0", "errors": []
{}
"message": "Field fieldThatIsWrong doesn't exist."
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.
ID of the account.
Account object with all of its fields.
account null |
AccountCreateUpdate
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
200 Updated account successfully.
400 Bad request
404 Not found
{}
"account": {}
"name": "Construction Inc.", "languageCode": "en", "countryCode": "CA", "currency": "CAD", "notes": "This account is for the reporting needs of our construction project in Denver.", "autoImport": false, "field1": "Construction Inc.", "field2": "Annual reporting", "field3": "Spendings", "field4": "Reports", "field5": "Contractors", "field6": "Employees", "field7": "string", "field8": "string", "field9": "555-555-5555", "field10": "California", "field11": "USA", "field12": "Loans", "field13": "Budget", "field14": "string", "field15": "string", "field16": "string", "field17": "string", "field18": "string", "field19": "string", "field20": "string", "field21": 27, "field22": 34.09, "field23": 2, "field24": 8, "field25": 1, "field26": 1, "field27": 500, "field28": 2.91, "field29": 0, "field30": 0, "labels": []
{}
"name": "City", "value": "Los Angeles"
200 Updated account successfully.
400 Bad request
404 Not found
{}
"account": {}
"name": "Construction Inc.", "languageCode": "en", "countryCode": "CA", "currency": "CAD", "notes": "This account is for the reporting needs of our construction project in Denver.", "autoImport": false, "field1": "Construction Inc.", "field2": "Annual reporting", "field3": "Spendings", "field4": "Reports", "field5": "Contractors", "field6": "Employees", "field7": "string", "field8": "string", "field9": "555-555-5555", "field10": "California", "field11": "USA", "field12": "Loans", "field13": "Budget", "field14": "string", "field15": "string", "field16": "string", "field17": "string", "field18": "string", "field19": "string", "field20": "string", "field21": 27, "field22": 34.09, "field23": 2, "field24": 8, "field25": 1, "field26": 1, "field27": 500, "field28": 2.91, "field29": 0, "field30": 0, "labels": [],
{}
"name": "City", "value": "Los Angeles" "id": 738, "linkedAdPlatformAccounts": []
{}
"type": "string", "id": 0, "name": "Google Ads - Construction Inc.", "status": "ReadWrite", "adPlatformId": "444-444-4445", "accountId": 123, "currency": "CAD", "adPlatformType": "GoogleAds", "isLoginValid": true
{}
"error": {}
"message": "Field fieldThatIsWrong doesn't exist.", "status": 400, "internalErrorId": "37eae2d9-65bf-4360-8950-450e1bd61dc0", "errors": []
{}
"message": "Field fieldThatIsWrong doesn't exist."
{}
"error": {}
"message": "Field fieldThatIsWrong doesn't exist.", "status": 400, "internalErrorId": "37eae2d9-65bf-4360-8950-450e1bd61dc0", "errors": []
{}
"message": "Field fieldThatIsWrong doesn't exist."
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.
ID of the account.
Account object with the fields to update.
account null |
AccountCreateUpdate
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
200 Partly updated account successfully.
400 Bad request
404 Not found
{}
"account": {}
"name": "Construction Inc.", "languageCode": "en", "countryCode": "CA", "currency": "CAD", "notes": "This account is for the reporting needs of our construction project in Denver.", "autoImport": false, "field1": "Construction Inc.", "field2": "Annual reporting", "field3": "Spendings", "field4": "Reports", "field5": "Contractors", "field6": "Employees", "field7": "string", "field8": "string", "field9": "555-555-5555", "field10": "California", "field11": "USA", "field12": "Loans", "field13": "Budget", "field14": "string", "field15": "string", "field16": "string", "field17": "string", "field18": "string", "field19": "string", "field20": "string", "field21": 27, "field22": 34.09, "field23": 2, "field24": 8, "field25": 1, "field26": 1, "field27": 500, "field28": 2.91, "field29": 0, "field30": 0, "labels": []
{}
"name": "City", "value": "Los Angeles"
200 Partly updated account successfully.
400 Bad request
404 Not found
{}
"account": {}
"name": "Construction Inc.", "languageCode": "en", "countryCode": "CA", "currency": "CAD", "notes": "This account is for the reporting needs of our construction project in Denver.", "autoImport": false, "field1": "Construction Inc.", "field2": "Annual reporting", "field3": "Spendings", "field4": "Reports", "field5": "Contractors", "field6": "Employees", "field7": "string", "field8": "string", "field9": "555-555-5555", "field10": "California", "field11": "USA", "field12": "Loans", "field13": "Budget", "field14": "string", "field15": "string", "field16": "string", "field17": "string", "field18": "string", "field19": "string", "field20": "string", "field21": 27, "field22": 34.09, "field23": 2, "field24": 8, "field25": 1, "field26": 1, "field27": 500, "field28": 2.91, "field29": 0, "field30": 0, "labels": [],
{}
"name": "City", "value": "Los Angeles" "id": 738, "linkedAdPlatformAccounts": []
{}
"type": "string", "id": 0, "name": "Google Ads - Construction Inc.", "status": "ReadWrite", "adPlatformId": "444-444-4445", "accountId": 123, "currency": "CAD", "adPlatformType": "GoogleAds", "isLoginValid": true
{}
"error": {}
"message": "Field fieldThatIsWrong doesn't exist.", "status": 400, "internalErrorId": "37eae2d9-65bf-4360-8950-450e1bd61dc0", "errors": []
{}
"message": "Field fieldThatIsWrong doesn't exist."
{}
"error": {}
"message": "Field fieldThatIsWrong doesn't exist.", "status": 400, "internalErrorId": "37eae2d9-65bf-4360-8950-450e1bd61dc0", "errors": []
{}
"message": "Field fieldThatIsWrong doesn't exist."
Deletes a single account from the Acquisio Organization. This action will also remove all entities within the deleted account from the Acquisio Organization. Note: The Ad Platform accounts, campaigns and all child entities will be removed from the Acquisio Organization, however, they will remain unchanged at the Ad Platform.
ID of the account.
200 Delete successful
ID of the asynchronous job that has been created to delete the account.
The Jobs endpoints allow to track the progress of the job.
X-JobId is the id
of the Job
resource.
400 Bad request
404 Not found
200 Delete successful
400 Bad request
404 Not found
{ }
{}
"error": {}
"message": "Field fieldThatIsWrong doesn't exist.", "status": 400, "internalErrorId": "37eae2d9-65bf-4360-8950-450e1bd61dc0", "errors": []
{}
"message": "Field fieldThatIsWrong doesn't exist."
{}
"error": {}
"message": "Field fieldThatIsWrong doesn't exist.", "status": 400, "internalErrorId": "37eae2d9-65bf-4360-8950-450e1bd61dc0", "errors": []
{}
"message": "Field fieldThatIsWrong doesn't exist."
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. Parents: None. Children: Ad Platform Account (for Ad Platform accounts that are associated to an Ad Platform master account).Hierarchy
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. Parents: None. Children: None.Hierarchy
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: 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: Parents: Account, Ad Platform Master Account
(if the Ad Platform account is associated to an Ad Platform master account). Children: Campaign. Ad Platform accounts have statistics that can be retrieved with the Reporting API.
Hierarchy
Statistics
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 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: Note: To automatically import all campaigns from linked Ad Platform accounts,
the autoImport field of the account must be set to "true". Parents: Ad Platform Account. Children: A campaign has various children (like Ad Groups, Keywords and Ads) which are not available through the Provisioning API. The statistics of Campaigns, Ad Groups, Keywords and Ads can be retrieved with the Reporting API.Importing campaigns to Acquisio
Hierarchy
Statistics
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.