swagger: "2.0" info: title: Provisioning API description: | 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](https://adwords.google.com), [Microsoft Advertising](https://ads.microsoft.com/) and [Facebook](https://www.facebook.com/business/products/ads). 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](https://adwords.google.com/intl/en_ca/home/tools/manager-accounts/) (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](https://about.ads.microsoft.com/en-us/partners/welcome). 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](#operation/cloneCampaigns) # 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](#tag/Labels). The labels set with Provisioning API can also be retrieved with [Reporting API](../../reporting/v0/#section/Advanced/Advanced-filters-on-labels). # Versioning All Acquisio APIs are versioned the same way. For more information, refer to [Versioning](../../versioning). Backward-compatible changes are documented in the [Provisioning API v0 Release Notes](release-notes/). # Security The Provisioning API is secured with OAuth 2.0. For more information about the security, see [Getting Started](../../../guides/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 | # 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](#operation/cloneCampaigns). Many HTTP status (like 403 or 500) are used the same way in all Acquisio APIs. For a complete list, please consult [Error Codes](../../error-codes/). version: v0 contact: email: api@acquisio.com host: api.acquisio.com basePath: /provisioning/v0 schemes: - https consumes: - application/json produces: - application/json securityDefinitions: oauth2ClientCredentials: type: oauth2 flow: application tokenUrl: https://api.acquisio.com/token security: - oauth2ClientCredentials: [] tags: - name: Accounts description: | 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](#tag/Ad-Platform-Accounts). ## Statistics Accounts have statistics that can be retrieved with the [Reporting API](../../reporting/v0/#tag/Accounts). ## 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. | 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 | - name: Ad Platform Master Accounts description: | 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](#tag/Ad-Platform-Accounts) (for Ad Platform accounts that are associated to an Ad Platform master account). - name: Ad Platform Master Reseller Accounts description: | Organizations who are partnered with Microsoft Advertising through the [Microsoft Advertising Partners Program](https://about.ads.microsoft.com/en-us/partners/welcome) 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. - name: Ad Platform Accounts description: | 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](#tag/Accounts), [Ad Platform Master Account](#tag/Ad-Platform-Master-Accounts) (if the Ad Platform account is associated to an Ad Platform master account). Children: [Campaign](#tag/Campaigns). ## Statistics Ad Platform accounts have statistics that can be retrieved with the [Reporting API](../../reporting/v0/#tag/Ad-Platform-Accounts). - name: Campaigns description: | 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](#operation/postAccount) must be set to "true". ## Hierarchy Parents: [Ad Platform Account](#tag/Ad-Platform-Accounts). 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](../../reporting/v0). ## 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](https://www.clientcampaigns.com/). `acquisio:campaignGroup` isn't supported yet by the endpoints dedicated to the labels, it can only be used when importing campaigns. - name: Jobs description: | 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. x-tagGroups: - name: Endpoints tags: - Accounts - Ad Platform Master Accounts - Ad Platform Master Reseller Accounts - Ad Platform Accounts - Campaigns - Power Cloner - Labels - Jobs paths: /accounts: post: tags: - Accounts summary: Create a new account description: | 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. operationId: postAccount parameters: - in: body name: body description: Account resource to create. required: true schema: $ref: "#/definitions/AccountRequest" responses: 201: description: Creation of a single account was successful. schema: $ref: "#/definitions/AccountResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" get: tags: - Accounts summary: Retrieve a list of accounts description: | Retrieves a list of accounts with its linked Ad Platform accounts. operationId: listAccounts parameters: - $ref: "#/parameters/limitParam" - $ref: "#/parameters/offsetParam" - $ref: "#/parameters/labelParam" - name: id in: query description: | 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. required: false type: array items: type: integer format: int64 collectionFormat: csv responses: 200: description: Listed accounts successfully headers: X-TotalCount: description: | Count of total available resources. type: number format: int64 schema: $ref: "#/definitions/AccountsResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" /accounts/id/{id}: get: tags: - Accounts summary: Retrieve a single account description: Retrieve a single account with its linked Ad Platform accounts. operationId: getAccount parameters: - name: id in: path description: ID of the account. required: true type: integer format: int64 responses: 200: description: Get single account successfully schema: $ref: "#/definitions/AccountResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" put: tags: - Accounts summary: Overwrite an account description: | 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. operationId: putAccount parameters: - name: id in: path description: ID of the account. required: true type: integer format: int64 - in: body name: body description: Account object with all of its fields. required: true schema: $ref: "#/definitions/AccountRequest" responses: 200: description: Updated account successfully. schema: $ref: "#/definitions/AccountResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" patch: tags: - Accounts summary: Update an account (specific fields) description: | Updates only specified fields of a single account based on the ID in the endpoint. The update uses the [Json Merge Patch](https://tools.ietf.org/html/rfc7396) 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. operationId: patchAccount consumes: - "application/merge-patch+json" parameters: - name: id in: path description: ID of the account. required: true type: integer format: int64 - in: body name: body description: Account object with the fields to update. required: true schema: $ref: "#/definitions/AccountRequest" responses: 200: description: Partly updated account successfully. schema: $ref: "#/definitions/AccountResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" delete: tags: - Accounts summary: Delete an account description: | 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. operationId: deleteAccount parameters: - name: id in: path description: ID of the account. required: true type: integer format: int64 responses: 200: description: Delete successful headers: X-JobId: description: | ID of the asynchronous job that has been created to delete the account. The [Jobs](#tag/Jobs) endpoints allow to track the progress of the job. X-JobId is the `id` of the `Job` resource. type: integer format: int64 examples: application/json: { } 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" /accounts/id/{accountId}/campaigns: get: tags: - Campaigns summary: Retrieve a list of campaigns in an account description: | Retrieves a complete list of campaigns linked to an account. Note: Only imported campaigns are returned by this endpoint. To retrieve a list of campaigns in an Ad Platform account use [GET /adplatform-accounts/id/{id}/campaigns](#operation/listCampaignsForAdPlatformAccount). operationId: listCampaignsForAccount parameters: - name: accountId in: path description: ID of the account. required: true type: integer format: int64 - $ref: "#/parameters/limitParam" - $ref: "#/parameters/offsetParam" responses: 200: description: Listed campaigns successfully headers: X-TotalCount: description: | Count of total available resources. type: number format: int64 schema: $ref: "#/definitions/CampaignsResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" /accounts/id/{accountId}/clone-campaigns: post: tags: - Power Cloner summary: Clone-sync campaigns with the Power Cloner description: | Power Cloner is designed to Clone Campaigns and their assets from Google Ads to Microsoft Advertising. Notes: - When the Power Cloner is enabled the following assets are cloned and synced: - Campaigns - Ad groups - Keywords - Text ads and expanded text ads - Negative keywords (for campaigns and ad groups) - Device targets (also known as mobile bid adjustment) (for campaigns and ad groups) - Location targets, negative location targets and radius targets (for campaigns) - Sitelink extensions (for campaigns and ad groups) - This endpoint initiates a Power Cloner job for a list of Google Ads campaigns that are provided. Google Ads campaigns that have already been cloned will be synced. - When the "Bid Budget Management" feature has been activated for an account in the Acquisio UI or otherwise, bids and budgets aren't cloned or synced. ### Partial errors This endpoint supports partial errors. The operation will be attempted for each resource and errors will be available for the operations that couldn't be completed. The status code will be successful even if one or many errors happen. operationId: cloneCampaigns parameters: - name: accountId in: path description: ID of the account. required: true type: integer format: int64 - in: body name: body required: true schema: $ref: "#/definitions/CloneCampaignsRequest" responses: 202: description: Clone successful headers: X-JobId: description: | ID of the asynchronous job that has been created to clone-sync the campaigns. The [Jobs](#tag/Jobs) endpoints allow to track the progress of the job. X-JobId is the `id` of the `Job` resource. type: integer format: int64 schema: $ref: "#/definitions/CloneCampaignsResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" /adplatform-master-accounts: get: tags: - Ad Platform Master Accounts summary: Retrieve a list of Ad Platform master accounts description: | Get the list of the linked Ad Platform accounts under many Ad Platform master accounts. Note: If an Ad Platform account is associated to more than 1 Acquisio account, a record will be returned for each of the Acquisio Accounts. operationId: listAdPlatformMasterAccounts parameters: - $ref: "#/parameters/limitParam" - $ref: "#/parameters/offsetParam" - name: id in: query description: | List of Ad Platform master account IDs separated by a comma. If `id` is omitted, all available master accounts are returned. If `id` is provided, only the master accounts included in `id` will be returned. required: false type: array items: type: integer format: int64 collectionFormat: csv responses: 200: description: Listed Ad Platform master accounts successfully headers: X-TotalCount: description: | Count of total available resources. type: number format: int64 schema: $ref: "#/definitions/AdPlatformMasterAccountsResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" /adplatform-master-accounts/id/{id}/adplatform-accounts: get: tags: - Ad Platform Master Accounts summary: Retrieve a list of Ad Platform accounts in an Ad Platform master account description: | Retrieves all linked and unlinked Ad Platform accounts contained in an Ad Platform master account. The payload will include a list of Acquisio account IDs for each Ad Platform account that is linked to one or more Acquisio Accounts. operationId: listAdPlatformAccountsByMasterAccount parameters: - name: id in: path description: ID of the Ad Platform master account. required: true type: integer format: int64 - name: embed in: query description: | `embed` is a list of sub-resources that can optionally be returned in the response (currently only available for Google Ads). By default, `embed` is empty and all the `embed` fields will be null. | Embed sub-resource | Description | |-----------------------|-------------------------------------------------------------------------------------------------------------| | childrenAccounts | If `&embed=childrenAccounts`, then the list of the children accounts are retrieved. | | childrenAdPlatformIds | If `&embed=childrenAdPlatformIds`, then the list of Ad Platform IDs of the children accounts are retrieved. | type: array items: type: string collectionFormat: csv responses: 200: description: Get Ad Platform managed accounts successfully schema: $ref: "#/definitions/AdPlatformManagedAccountsResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" /adplatform-master-accounts/id/{id}/billing-accounts: get: tags: - Ad Platform Master Accounts summary: Retrieve a list of the billing accounts in an AdPlatform master account (Google Ads only) description: | Retrieves the billing accounts of a linked AdPlatform master account. Only Google Ads billing accounts are currently supported. operationId: listBillingAccountsByMasterAccount parameters: - name: id in: path description: ID of the Ad Platform master account. required: true type: integer format: int64 - name: currency in: query description: | ISO 4217 [currency code](../../system-codes/#currency-codes) of the billing accounts that must be returned. If `currency` is omitted, all available billing accounts of the AdPlatform master account are returned. required: false type: string responses: 200: description: Get billing accounts successfully schema: $ref: "#/definitions/BillingAccountResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" /adplatform-master-accounts/id/{id}: get: tags: - Ad Platform Master Accounts summary: Retrieve a single Ad Platform master account description: | Get the list of the linked Ad Platform accounts under an Ad Platform master account. Note: If an Ad Platform account is associated to more than 1 Acquisio account, a record will be returned for each of the Acquisio Accounts operationId: getAdPlatformMasterAccount parameters: - name: id in: path description: ID of the Ad Platform master account requested. required: true type: integer format: int64 responses: 200: description: Get Ad Platform master account successfully schema: $ref: "#/definitions/AdPlatformMasterAccountResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" delete: tags: - Ad Platform Master Accounts summary: Delete an Ad Platform master account description: | Deletes the association of the Ad Platform master account to the Acquisio Organization. Note: This action will unlink all child Ad Platform accounts. The imported campaign will continue to be visible in the Acquisio UI but will be in a read only state and will remain unchanged at the Ad Platform. operationId: deleteAdPlatformMasterAccount parameters: - name: id in: path description: ID of the Ad Platform master account. required: true type: integer format: int64 responses: 200: description: Delete successful headers: X-JobId: description: | ID of the asynchronous job that has been created to delete the Ad Platform master account. The [Jobs](#tag/Jobs) endpoints allow to track the progress of the job. X-JobId is the `id` of the `Job` resource. type: integer format: int64 examples: application/json: { } 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" /adplatform-master-reseller-accounts: get: tags: - Ad Platform Master Reseller Accounts summary: Retrieve a list of Ad Platform master reseller accounts (Microsoft Advertising only) description: Retrieves a list of all Ad Platform master reseller accounts that exist in the Acquisio Organization. For each Ad Platform master reseller account, there is a list of attributes including its `adPlatformCustomerId`. operationId: listAdPlatformMasterResellerAccounts parameters: - $ref: "#/parameters/limitParam" - $ref: "#/parameters/offsetParam" - name: id in: query description: | List of Ad Platform master reseller account IDs separated by a comma. If `id` is omitted, all available master reseller accounts are returned. If `id` is provided, only the master reseller accounts included in `id` will be returned. required: false type: array items: type: integer format: int64 collectionFormat: csv responses: 200: description: Listed Ad Platform master reseller accounts successfully headers: X-TotalCount: description: | Count of total available resources. type: number format: int64 schema: $ref: "#/definitions/AdPlatformMasterResellerAccountsResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" /adplatform-master-reseller-accounts/id/{id}: get: tags: - Ad Platform Master Reseller Accounts summary: Retrieve a single Ad Platform master reseller account (Microsoft Advertising only) description: Get a single Ad Platform master reseller account. operationId: getAdPlatformMasterResellerAccount parameters: - name: id in: path description: ID of the Ad Platform master reseller account requested. required: true type: integer format: int64 responses: 200: description: Get Ad Platform master reseller account successfully schema: $ref: "#/definitions/AdPlatformMasterResellerAccountResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" delete: tags: - Ad Platform Master Reseller Accounts summary: Delete an Ad Platform master reseller account (Microsoft Advertising only) description: Deletes the Ad Platform master reseller account from the Acquisio platform. operationId: deleteAdPlatformMasterResellerAccount parameters: - name: id in: path description: ID of the Ad Platform master reseller account. required: true type: integer format: int64 responses: 200: description: Delete successful headers: X-JobId: description: | ID of the asynchronous job that has been created to delete the Ad Platform master reseller account. The [Jobs](#tag/Jobs) endpoints allow to track the progress of the job. X-JobId is the `id` of the `Job` resource. type: integer format: int64 examples: application/json: { } 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" /adplatform-accounts/link: post: tags: - Ad Platform Accounts summary: Link an existing Ad Platform account description: | This action will link an existing Ad Platform account by providing the IDs for the Ad Platform account, the parent Ad Platform master account and the Acquisio account. Note: Linking an Ad Platform account creates a connection between the Acquisio Platform and the Ad Platform. This connection makes it possible to import campaigns and allows the Acquisio platform to retrieve daily statistics for these campaigns (clicks, impressions, etc.). operationId: linkAdPlatformAccount parameters: - in: body name: body description: Ad Platform account to be linked required: true schema: $ref: "#/definitions/LinkAdPlatformAccountRequest" responses: 200: description: Link Ad Platform account successful schema: $ref: "#/definitions/AdPlatformAccountResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" /adplatform-accounts: post: tags: - Ad Platform Accounts summary: Create a new Ad Platform account description: | This action will create a new Ad Platform and link it to an Acquisio account by providing the IDs for the parent Ad Platform master account and the Acquisio account. Creating an Ad Platform account also establishes a connection between the Acquisio Platform and the Ad Platform. This connection makes it possible to import campaigns and allows the Acquisio platform to retrieve daily statistics for these campaigns (clicks, impressions, etc.). Note: For Microsoft Advertising, Ad Platform accounts need to be created in the context of a [master reseller account](#tag/Ad-Platform-Master-Reseller-Accounts). operationId: postAdPlatformAccount parameters: - in: body name: body description: Ad Platform account to be created required: true schema: $ref: "#/definitions/CreateAdPlatformAccountRequest" responses: 200: description: Created an Ad Platform account successfully schema: $ref: "#/definitions/CreateAdPlatformAccountResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" get: tags: - Ad Platform Accounts summary: Retrieve a list of Ad Platform accounts description: | Retrieves a list of Ad Platform accounts. operationId: listAdPlatformAccounts parameters: - $ref: "#/parameters/limitParam" - $ref: "#/parameters/offsetParam" - name: id in: query description: | List of Ad Platform account IDs separated by a comma. If `id` is omitted, all available Ad Platform accounts are returned. If `id` is provided, only the Ad Platform accounts included in `id` will be returned. required: false type: array items: type: integer format: int64 collectionFormat: csv - name: accountId in: query description: | List of Account IDs separated by a comma. If `accountId` is omitted, all available Ad Platform accounts are returned. If `accountId` is provided, only the Ad Platform accounts with Account ID included in `accountId` will be returned. required: false type: array items: type: integer format: int64 collectionFormat: csv responses: 200: description: List of Ad Platform accounts headers: X-TotalCount: description: | Count of total available resources. type: number format: int64 schema: $ref: "#/definitions/AdPlatformAccountsResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" /adplatform-accounts/id/{id}: get: tags: - Ad Platform Accounts summary: Retrieve a single Ad Platform account description: Retrieve a single Ad Platform account. operationId: getAdPlatformAccount parameters: - name: id in: path description: ID of the Ad Platform account. required: true type: integer format: int64 responses: 200: description: A single Ad Platform account schema: $ref: "#/definitions/AdPlatformAccountResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" delete: tags: - Ad Platform Accounts summary: Delete an Ad Platform account description: | Deletes the Ad Platform account from the Acquisio platform. Campaigns will be removed from Acquisio's platform without deleting them at the Ad Platform. operationId: deleteAdPlatformAccount parameters: - name: id in: path description: ID of the Ad Platform account. required: true type: integer format: int64 responses: 200: description: Delete successful headers: X-JobId: description: | ID of the asynchronous job that has been created to delete the Ad Platform account. The [Jobs](#tag/Jobs) endpoints allow to track the progress of the job. X-JobId is the `id` of the `Job` resource. type: integer format: int64 examples: application/json: { } 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" /adplatform-accounts/relink: post: tags: - Ad Platform Accounts summary: Relink many Ad Platform accounts description: | Relink an Ad Platform account that was previously unlinked, recreating the connection between Acquisio and the Ad Platform. The Ad Platform accounts to relink must be under a linked Ad Platform master account. If the master account is unlinked, then the Ad Platform accounts cannot be relinked. Relinking restore functionalities that are no longer available when the Ad Platform accounts are unlinked, like listing campaigns from the Ad Platform or retrieving the daily statistics of imported campaigns. ### Partial errors This endpoint supports partial errors. The operation will be attempted for each resource and errors will be available for the operations that couldn't be completed. The status code will be successful even if one or many errors happen. operationId: relinkAdPlatformAccounts parameters: - in: body name: body description: The required list of Ad Platform account IDs and the Ad Platform master account ID to relink them from. required: true schema: $ref: "#/definitions/RelinkAdPlatformAccountsRequest" responses: 200: description: A list of Ad Platform accounts successfully linked and errors for the Ad Platform accounts that could not be relinked. schema: $ref: "#/definitions/RelinkAdPlatformAccountsResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" /adplatform-accounts/unlink: post: tags: - Ad Platform Accounts summary: Unlink many Ad Platform accounts description: | Unlinks a list of Ad Platform accounts from the Acquisio platform. Unlinking will sever the connection to the Ad Platform. The campaigns will be left on Acquisio's platform, but it won't be possible to update them or get their daily statistics (clicks, impression, etc.). operationId: unlinkAdPlatformAccounts parameters: - in: body name: body description: The required list of Ad Platform account IDs and the Ad Platform master account ID to relink them from. required: true schema: $ref: "#/definitions/UnlinkAdPlatformAccountsRequest" responses: 200: description: Unlink successful examples: application/json: { } 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" /adplatform-accounts/id/{id}/unlink: post: tags: - Ad Platform Accounts summary: Unlink an Ad Platform account description: | Unlinks a single Ad Platform account from the Acquisio platform. Unlinking will sever the connection to the Ad Platform. The campaigns will be left on Acquisio's platform, but it won't be possible to update them or get their daily statistics (clicks, impression, etc.). operationId: unlinkAdPlatformAccount parameters: - name: id in: path description: ID of the Ad Platform account. required: true type: integer format: int64 responses: 200: description: Unlink successful examples: application/json: { } 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" /adplatform-accounts/id/{adPlatformAccountId}/campaigns: get: tags: - Campaigns summary: Retrieve a list of campaigns in an Ad Platform account description: | Retrieves a list of all the campaigns in a linked Ad Platform account. Use the `includeUnimported` query parameter to include campaigns that have not been imported along with the imported campaigns. Note: Campaigns that are imported have a non-null `id` field, while unimported campaigns have a null `id`. ### Sorting The sorting of this endpoint is done in ascendant order by the `id` attribute, then by the `adPlatformId` attribute. Campaigns with a null `id` are returned before campaigns with a non-null `id`. Note: After a campaign has been imported, its `id` will no longer be null and the campaign may be returned on a different page than it was prior to being imported. operationId: listCampaignsForAdPlatformAccount parameters: - name: adPlatformAccountId in: path description: ID of the Ad Platform account. required: true type: integer format: int64 - $ref: "#/parameters/limitParam" - $ref: "#/parameters/offsetParam" - name: includeUnimported in: query description: | Listing campaigns can be done in two different ways. - If `includeUnimported` is omitted or set to false, all the campaigns of the Ad Platform account that are imported in the Acquisio platform will be listed. - If `includeUnimported` is set to true, all the campaigns of the Ad Platform account will be listed, even the campaigns that have not been imported yet in the Acquisio platform. required: false type: boolean responses: 200: description: Listed campaigns successfully headers: X-TotalCount: description: | Count of total available resources. type: number format: int64 schema: $ref: "#/definitions/CampaignsResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" /campaigns/import: post: tags: - Campaigns summary: Import campaigns from an Ad Platform description: | Import campaigns from a linked Ad Platform account to an Acquisio account. Notes: - 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. - Importing campaigns is an asynchronous operation. Making modifications to campaigns before the import process is finished is not recommended. ### See also The Provisioning API provides additional ways of automatically importing campaigns: - The [autoImport field of an account](#operation/postAccount) can be set to true to automatically import all campaigns in its linked Ad Platform accounts - The `importAllCampaigns` field of an Ad Platform account can be set to true when [an Ad Platform account is linked in an Acquisio account](#operation/linkAdPlatformAccount) to automatically import all campaigns to the Acquisio account to which it is linked. operationId: importCampaigns parameters: - in: body name: body required: true schema: $ref: "#/definitions/ImportCampaignsRequest" responses: 202: description: Request successful headers: X-JobId: description: | ID of the asynchronous job that has been created to import the campaigns. The [Jobs](#tag/Jobs) endpoints allow to track the progress of the job. X-JobId is the `id` of the `Job` resource. type: integer format: int64 examples: application/json: { } 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" /campaigns/id/{id}: delete: tags: - Campaigns summary: Delete a campaign description: | Deletes a campaign from the Acquisio platform and at the Ad Platform. Note: The impact of deleting of a campaign varies according to the policy of the Ad Platform: - For Google Ads, the status of the campaign is set to deleted. The campaign is still visible but can not be edited. A deleted campaign will be removed from Google Ads after an unspecified period of time. - For Microsoft Advertising, the campaign is removed from the Microsoft Advertising platform and can no longer be viewed. To remove an Google Ads campaign from the Acquisio platform without deleting it at the Ad Platform use this endpoint [POST /campaigns/id/{id}/unlink](#operation/unlinkCampaign) instead. operationId: deleteCampaign parameters: - name: id in: path description: ID of the campaign to delete. required: true type: integer format: int64 responses: 200: description: Delete successful headers: X-JobId: description: | ID of the asynchronous job that has been created to delete the campaign. The [Jobs](#tag/Jobs) endpoints allow to track the progress of the job. X-JobId is the `id` of the `Job` resource. type: integer format: int64 examples: application/json: { } 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" /campaigns/id/{id}/unlink: post: tags: - Campaigns summary: Unlink a campaign description: | Unlinks a campaign from the Acquisio platform. This action will remove the campaign from Acquisio's platform, but will keep it intact at the Ad Platform. operationId: unlinkCampaign parameters: - name: id in: path description: ID of the campaign to unlink. required: true type: integer format: int64 responses: 200: description: Unlink successful examples: application/json: { } 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" /labels/resource/{resource}: get: tags: - Labels summary: Retrieve a list of labels for a type of ressource description: | List the labels of the accounts or the campaigns. The label values set for each account or campaign are also returned. operationId: listResourceLabels parameters: - name: resource in: path description: | The type of resource for which labels must be returned. | Resource | |----------| | account | | campaign | required: true type: string - name: accountId in: query description: | ID of the account to get the labels from. Mandatory if `resource` is not `account`. type: integer format: int64 responses: 200: description: Listed resource labels successfully schema: $ref: "#/definitions/ResourceLabelsResponse" post: tags: - Labels summary: Create and edit labels on many resources description: | Allows to create and edit the labels of an account or campaign. The label values will be set on a specific account or campaign. If a label has a name that is different than the names of existing labels, then a new label will be created with that name. A label value can be deleted by sending the name of the label with a null value or an empty string. Label names are case sensitive. The `id` of each label is optional. It can be provided to trigger an error if a label has been renamed, instead of creating a new label. operationId: bulkEditResourceLabels parameters: - name: resource in: path description: | The type of resource for which the labels must be edited. |Resource| |--------| |account | |campaign| required: true type: string - name: accountId in: query description: | ID of the account to get the labels from. Mandatory if `resource` is not `account`. type: integer format: int64 - in: body name: body required: true schema: $ref: "#/definitions/BulkEditResourceLabelsRequest" responses: 200: description: Bulk edit successful schema: $ref: "#/definitions/ApiPartialErrorsResponse" /labels: get: tags: - Labels summary: Retrieve a list of labels description: | Retrieve a list of labels with the values that have been set for those labels. The labels are returned without their association to an account or a campaign. Labels that have been used in the past, but no longer have values, will not be returned. This endpoint is useful to find the usage of the labels across all accounts and/or campaigns. For example, it can list all the values that have been set for a `City` label. operationId: getLabels responses: 200: description: Listed labels successfully schema: $ref: "#/definitions/LabelsResponse" /labels/name/{name}: post: tags: - Labels summary: Create a new label description: | Create a new label with a name and no values. The name must not be the same than an existing label. This endpoint is useful to build user interfaces in which a user can type the name of a label without setting any value. For other usages, the endpoint [POST /labels/resource/{resource}](#operation/bulkEditResourceLabels) allows to create labels and set their values. operationId: createLabelName parameters: - name: name in: path description: Name of the label to create. required: true type: string minLength: 1 maxLength: 30 responses: 200: description: Created label successfully schema: $ref: "#/definitions/LabelNameUpdateContainer" put: tags: - Labels summary: Update the name of a label description: | Update the name of a label. The name must not be used by an existing label. This endpoint is useful to rename a label without changing its ID. operationId: updateLabelName parameters: - name: name in: path description: Name of the label to update. required: true type: string minLength: 1 maxLength: 30 - in: body name: body required: true schema: $ref: "#/definitions/LabelNameUpdateContainer" responses: 200: description: Updated label name successfully schema: $ref: "#/definitions/LabelNameUpdateContainer" delete: tags: - Labels summary: Delete the values of a label description: | Delete the values of a label. The `value` query parameter allows to only delete a specific value, while keeping other values. The `accountId` query parameter allows to remove the values from specific accounts. If `value` and `accountId` aren't set, the label itself will be deleted and all its values. operationId: deleteLabelValues parameters: - name: name in: path description: Name of the label to delete values from. required: true type: string minLength: 1 maxLength: 30 - name: value in: query description: Value of the label to delete. required: false type: string minLength: 1 maxLength: 4000 - name: accountId in: query description: IDs of the accounts to delete the label values from. required: false type: array items: type: integer format: int64 collectionFormat: csv responses: 200: description: Deleted label values successfully examples: application/json: { } /jobs: get: tags: - Jobs summary: Retrieve a list of jobs description: | Retrieves a list of jobs initiated in the the last seven days. This includes asynchronous jobs such as importing a campaign, cloning a campaign, or deleting a resource. operationId: listJobs parameters: - $ref: "#/parameters/limitParam" - $ref: "#/parameters/offsetParam" - name: id in: query description: | List of job IDs separated by a comma. If `id` is omitted, all available jobs are returned. If `id` is provided, only the jobs included in `id` will be returned. The IDs are provided by endpoints that start an asynchronous job in the response header named `X-JobId`. required: false type: array items: type: integer format: int64 collectionFormat: csv - name: accountId in: query description: ID of the account related to the jobs. required: false type: integer format: int64 responses: 200: description: Listed jobs successfully headers: X-TotalCount: description: | Count of total available resources. type: number format: int64 schema: $ref: "#/definitions/JobsResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" /jobs/id/{id}: get: tags: - Jobs summary: Retrieve a single job description: | Retrieves details about a specific job initiated in the the last seven days. operationId: getJob parameters: - name: id in: path description: | ID of the job. This ID is provided by endpoints that start an asynchronous job in the response header named `X-JobId`. required: true type: integer format: int64 - name: accountId in: query description: ID of the account related to the job. required: false type: integer format: int64 responses: 200: description: Listed job successfully schema: $ref: "#/definitions/JobResponse" 400: description: Bad request schema: $ref: "#/definitions/ApiErrorResponse" 404: description: Not found schema: $ref: "#/definitions/ApiErrorResponse" parameters: offsetParam: name: offset in: query description: | 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. required: false type: integer format: int64 limitParam: name: limit in: query description: | Size of the page that will be returned in the response. - The maximum allowed value is 100. - The default value is 100. required: false type: integer format: int64 labelParam: name: labels in: query description: | 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. required: false type: array items: type: string collectionFormat: csv definitions: ApiErrorResponse: type: object properties: error: $ref: "#/definitions/ApiErrorResponseError" ApiPartialErrorsResponse: type: object properties: partialErrors: type: array items: $ref: "#/definitions/ApiErrorResponseError" ApiErrorResponseError: type: object properties: message: description: | An error message that explains why the request failed. If more than one error causes the request to fail, `error` is a generic error message. Details for each error are available in the `errors` array field. type: string example: Field fieldThatIsWrong doesn't exist. status: description: | HTTP status associated to this error. The HTTP status can be successful (like 200) for endpoints that return partial errors. type: integer format: int32 example: 400 internalErrorId: description: | Unique error identifier for tracking purposes. The format of `internalErrorId` might not stay constant over time. type: string example: 37eae2d9-65bf-4360-8950-450e1bd61dc0 errors: type: array items: $ref: "#/definitions/ApiError" ApiError: type: object properties: message: description: | An error message that explains why the request failed. type: string example: Field fieldThatIsWrong doesn't exist. AccountCreateUpdate: allOf: - $ref: "#/definitions/AccountBase" - type: object Account: allOf: - $ref: "#/definitions/AccountBase" - type: object properties: id: description: ID of the account. type: integer format: int64 example: 738 linkedAdPlatformAccounts: type: array items: $ref: "#/definitions/AdPlatformAccount" AccountBase: type: object properties: name: type: string description: Name of the account. example: Construction Inc. languageCode: type: string description: | Language code of two letters. The available languages depend on the country. Available [language-country combinations](#tag/Accounts). example: en countryCode: type: string description: | Country code of two letters. The country determines which languages are available. Available [language-country combinations](#tag/Accounts). example: CA currency: type: string description: | The currency code determines in which currency the monetary statistics (ex: cost) will be displayed in [Client Campaigns](https://www.clientcampaigns.com/). 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](../../system-codes/#currency-codes). example: CAD notes: type: string description: Notes related to the account. example: This account is for the reporting needs of our construction project in Denver. autoImport: type: boolean description: | 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. example: false field1: type: string example: Construction Inc. field2: type: string example: Annual reporting field3: type: string example: Spendings field4: type: string example: Reports field5: type: string example: Contractors field6: type: string example: Employees field7: type: string example: null field8: type: string example: null field9: type: string example: 555-555-5555 field10: type: string example: California field11: type: string example: USA field12: type: string example: Loans field13: type: string example: Budget field14: type: string example: null field15: type: string example: null field16: type: string example: null field17: type: string example: null field18: type: string example: null field19: type: string example: null field20: type: string example: null field21: type: number format: double example: 27 field22: type: number format: double example: 34.09 field23: type: number format: double example: 2 field24: type: number format: double example: 8 field25: type: number format: double example: 1 field26: type: number format: double example: 1 field27: type: number format: double example: 500 field28: type: number format: double example: 2.91 field29: type: number format: double example: 0 field30: type: number format: double example: 0 labels: type: array items: $ref: "#/definitions/Label" required: - name - languageCode - countryCode - currency AccountRequest: type: object properties: account: $ref: "#/definitions/AccountCreateUpdate" AccountResponse: type: object properties: account: $ref: "#/definitions/Account" AccountsResponse: type: object properties: accounts: type: array items: $ref: "#/definitions/Account" CloneCampaigns: type: object properties: destinationAdPlatformAccountId: type: integer format: int64 description: | ID of the Microsoft Advertising Ad Platform account to which the campaigns will be cloned.. - destinationAdPlatformAccountId is associated to the field `id` of the resource `Ad Platform Account`. - this field is ignored for campaigns that will be synced, since they will stay in their current Microsoft Advertising account. example: 63492 sourceCampaignIds: description: | Array of Google Ads campaign IDs to be cloned or synced. If sourceCampaignIds is omitted, then all Google Ads campaigns under the current account will be cloned or synced. - sourceCampaignsIds is associated to the field `id` of the resource `Campaign`. type: array items: type: integer format: int64 example: [12320, 12434, 12437] bidAdjustment: type: number format: double description: | Bid adjustment factor that will be applied for a cloned campaign. Minimum value is -0.99 and maximum value is 99.9. If it is -0.46, then all bids will be decreased by 46%. If it is 0.81, then all bids will be increased by 81%. If this value is omitted, then all Google Ads bids will be cloned as they are without any changes to Microsoft Advertising campaign. example: 0.81, budgetAdjustment: type: number format: double description: | Budget adjustment factor that will be applied for a cloned campaign. Minimum value is -0.99 and maximum value is 99.9. If it is -0.46, then budget will be decreased by 46%. If it is 0.81, then budget will be increased by 81%. If this value is omitted, then Google Ads budget will be cloned as it is without any changes to Microsoft Advertising campaign. example: -0.46 clonerSyncExclusions: type: array items: type: string description: | Exclusions allow to ignore a type of assert for a cloning or a syncing. - In a cloning, the assets that are excluded are not added to the Microsoft Advertising campaign. - In a syncing, the assets that are excluded are not added, modified or deleted in the Microsoft Advertising campaign. | Exclusion string | Description | |--------------------|---------------------------------------------------| | AdGroupBid | Adgroup bid | | AdGroupMobileBid | Adgroup mobile bid adjustment | | CampaignBudget | Campaign budget adjustment | | CampaignMobileBid | Campaign mobile bid adjustment | | CampaignStatus | Campaign status | | Keyword | Keyword | | KeywordBid | Keyword bid | | KeywordURL | Keyword URL | | LocationTargeting | Location and radius targets (for campaigns) | | NegativeKeyword | Negative keyword (for campaigns and ad groups) | | SiteLinkExtensions | Sitelink extensions (for campaigns and ad groups) | example: [CampaignStatus, KeywordURL] required: - destinationAdPlatformAccountId - sourceCampaignIds CloneCampaignsRequest: type: object properties: cloneCampaigns: $ref: "#/definitions/CloneCampaigns" CloneCampaignsResponse: type: object properties: partialError: $ref: "#/definitions/ApiErrorResponseError" LinkAdPlatformAccountRequest: type: object properties: linkAdPlatformAccount: $ref: "#/definitions/LinkAdPlatformAccount" LinkAdPlatformAccount: type: object discriminator: type properties: type: type: string description: | OpenAPI discriminator. Value can be `LinkGoogleAdsAdPlatformAccount` or `LinkMicrosoftAdvertisingAdPlatformAccount`. accountId: description: ID of the account where the Ad Platform will be linked to. type: integer format: int64 example: 200 name: type: string description: Name that identifies the Ad Platform account in the Acquisio platform. example: Hardware store masterAccountId: description: | ID of the master account. - masterAccountId is associated to the field `id` of the resource `AdPlatformMasterAccount` or to the field `id` of the resource `AdPlatformMasterResellerAccount`. type: integer format: int64 example: 35 importAllCampaigns: type: boolean description: | If this field is set to true, then all existing campaigns on Acquisio's platform under this Ad Platform account will be imported when the link will be made. Future campaigns created at the Ad Platform will not be automatically imported. To be able to import automatically your campaigns after the Ad Platform account is linked, the field `autoImport` of the [Acquisio account](#tag/Accounts) must be set to true. example: false required: - type - accountId - masterAccountId - name LinkGoogleAdsAdPlatformAccount: description: Create Google Ads account allOf: - $ref: "#/definitions/LinkAdPlatformAccount" - type: object properties: adPlatformId: type: integer format: int64 description: | ID that identifies the customer account in the API provided by the Ad Platform. - In the Provisioning API, adPlatformId is associated to the field `adPlatformId` of the resource `AdPlatformAccount`. - In the Google Ads API, adPlatformId is the field `customerId` of the type `Customer` in the CustomerService. example: 6238605114 required: - adPlatformId LinkMicrosoftAdvertisingAdPlatformAccount: description: Create Microsoft Advertising account allOf: - $ref: "#/definitions/LinkAdPlatformAccount" - type: object properties: adPlatformAccountNumber: type: string description: | Account number that identifies the number of the Microsoft Advertising account example: B0555J5H required: - adPlatformAccountNumber AdPlatformAccountResponse: type: object properties: adPlatformAccount: $ref: "#/definitions/AdPlatformAccount" CreateAdPlatformAccountResponse: allOf: - $ref: "#/definitions/AdPlatformAccountResponse" - type: object properties: partialError: $ref: "#/definitions/ApiErrorResponseError" AdPlatformAccountsResponse: type: object properties: adPlatformAccounts: type: array items: $ref: "#/definitions/AdPlatformAccount" RelinkAdPlatformAccountsResponse: type: object properties: adPlatformAccounts: type: array items: $ref: "#/definitions/AdPlatformAccount" partialError: $ref: "#/definitions/ApiErrorResponseError" RelinkAdPlatformAccountsRequest: type: object properties: relinkAdPlatformAccounts: $ref: "#/definitions/RelinkAdPlatformAccounts" RelinkAdPlatformAccounts: type: object properties: ids: type: array description: List of Ad Platform accounts to relink. items: type: integer format: int64 example: [12320, 12434, 12437] adPlatformMasterAccountId: description: ID of the master account that the Ad Platform accounts will be relinked to. type: integer format: int64 example: 35 required: - ids - adPlatformMasterAccountId UnlinkAdPlatformAccountsRequest: type: object properties: unlinkAdPlatformAccounts: $ref: "#/definitions/UnlinkAdPlatformAccounts" UnlinkAdPlatformAccounts: type: object properties: ids: type: array description: List of Ad Platform account IDs to unlink from the platform. items: type: integer format: int64 example: [12320, 12434, 12437] required: - ids CreateAdPlatformAccountRequest: type: object properties: createAdPlatformAccount: $ref: "#/definitions/CreateAdPlatformAccount" CreateAdPlatformAccount: type: object discriminator: type properties: type: type: string description: | OpenAPI discriminator. Value can be `CreateGoogleAdsAdPlatformAccount` or `CreateMicrosoftAdvertisingAdPlatformAccount`. accountId: type: integer description: ID of the account. format: int64 example: 200 name: type: string description: Name of the Ad Platform account that will be shown on Acquisio's platform. example: Hardware store adPlatformMasterAccountId: type: integer description: ID of the master account. format: int64 example: 35 currency: type: string description: | Currency of the Ad Platform account. - [Allowed values for Google Ads currency codes](https://developers.google.com/adwords/api/docs/appendix/codes-formats#currency-codes). - [Allowed currency codes for Microsoft Advertising](https://docs.microsoft.com/en-us/advertising/guides/currencies?view=bingads-13#bidandbudget) example: CAD timeZone: type: string description: | Time zone of Ad Platform account. - [Google Ads time zone codes](https://developers.google.com/adwords/api/docs/appendix/codes-formats#timezone-ids). - [Microsoft Advertising time zone codes](https://msdn.microsoft.com/en-us/library/bing-ads-time-zones(v=msads.100).aspx). example: America/Montreal required: - type - name - adPlatformMasterAccountId - currency - timeZone CreateGoogleAdsAdPlatformAccount: description: Create Google Ads account allOf: - $ref: "#/definitions/CreateAdPlatformAccount" - type: object properties: billingInfo: $ref: "#/definitions/CreateGoogleAdsBudgetOrder" CreateGoogleAdsBudgetOrder: description: Create Google Ads budget order type: object properties: endDateTime: type: string format: date-time description: End billing time in an ISO 8601 format. example: 2017-09-21T16:45:03 spendingLimit: type: number format: double description: Spending limit. example: 1.3 billingAccountId: type: string description: Billing account 16-digit ID. example: 1234-5678-9012-3456 primaryBillingId: type: string description: Primary billing account 12-digit ID. example: 1234-5678-9012 CreateMicrosoftAdvertisingAdPlatformAccount: description: Create Microsoft Advertising account allOf: - $ref: "#/definitions/CreateAdPlatformAccount" - type: object properties: adPlatformMasterResellerAccountId: type: integer description: Reseller ID of the account. format: int64 example: 300 industry: type: string description: | The primary business segment of the customer. | Values | |------------------------------| | AgencySalesHouse | | Automotive | | ConsumerPackagedGoods | | Education | | Entertainment | | FinancialServices | | FoodServices | | Gaming | | GovernmentNonprofitPolitical | | Healthcare | | Internal | | NA | | Other | | Pharmaceuticals | | PublishingAndWebMedia | | RealEstate | | Retail | | Services | | Technology | | Telecommunications | | TravelHospitality | example: ConsumerPackagedGoods marketCountry: type: string description: | The primary countryCode where the customer operates. For a list of customer market countryCode code values, see [Country Codes](../../system-codes/#country-codes). example: CA marketLanguage: type: string description: | The primary language that the customer uses. Your customer market language determines the language of the Microsoft Advertising interface. The complete list of allowed [customer market language codes](https://msdn.microsoft.com/library/bing-ads-ad-languages.aspx#productlanguage) is available in the Microsoft Advertising API documentation. | Values | |--------------------| | Arabic | | Danish | | Dutch | | English | | Finnish | | French | | German | | Hebrew | | Italian | | Japanese | | Korean | | Norwegian | | Portuguese | | Russian | | SimplifiedChinese | | Spanish | | Swedish | | TraditionalChinese | example: English agencyContactName: type: string description: | Agency contact name. required: - adPlatformMasterResellerAccountId - industry - marketCountry - marketLanguage CampaignsResponse: type: object properties: campaigns: type: array items: $ref: "#/definitions/Campaign" Campaign: type: object properties: id: description: | ID of the campaign. Some endpoints can return campaigns that have not been imported yet in the Acquisio platform. Unimported campaigns have a null ID. type: integer format: int64 example: 123 adPlatformId: description: | ID that identifies the campaign in the API provided by the Ad Platform. - In the Google Ads API, adPlatformId is the field `id` of the type `Campaign` in the CampaignService. - In the Microsoft Advertising API, adPlatformId is the element `id` of the data object `Campaign` in the Campaign Management Service. type: integer format: int64 example: 987456213 adPlatformType: type: string description: | Type of the Ad Platform account. | Values | |-----------------------| | Facebook | | GoogleAds | | MicrosoftAdvertising | name: type: string description: Name of the campaign at the Ad Platform. example: campaign name 2 status: type: string description: | Status of the Ad Platform campaign. | Values | |-----------| | Active | | Completed | | Deleted | | Draft | | Inactive | | Paused | | Suspended | | Unknown | example: Removed clonerSourceId: description: | If this campaign is a Microsoft Advertising campaign that was cloned from Google Ads with the Power Cloner, this field contains the ID of the Google Ads campaign that it originates from. type: integer format: int64 example: 123 clonerDestinationIds: description: | If this campaign is an Google Ads campaign that was cloned to Microsoft Advertising with the Power Cloner, this field contains the ID of the Microsoft Advertising campaign that originates from this campaign. type: array items: type: integer format: int64 description: If this campaign was the source of cloning jobs, this field will return the list of campaign IDs that it cloned. example: [123, 456, 789] ImportCampaignsRequest: type: object properties: importCampaigns: $ref: "#/definitions/ImportCampaigns" ImportCampaigns: type: object properties: adPlatformAccountId: description: ID of the Ad Platform account to import the campaigns from. type: integer format: int64 example: 38 campaignAdPlatformIds: type: array description: | List of Ad Platform campaign IDs to be imported. - [GET /adplatform-accounts/id/{id}/campaigns](#operation/listCampaignsForAdPlatformAccount) allows to know which campaigns have not yet been imported in the Acquisio platform. items: type: integer format: int64 example: [12320, 12434, 12437] labels: description: | Labels to apply on the campaigns that will be imported. A single label is currently supported, the `acquisio:campaignGroup` label. The labels created with Provisioning API aren't supported yet. The `acquisio:campaignGroup` label is mandatory, all campaigns must be imported within a campaign group. If no campaign group exists with the provided name, a new campaign group with that name will be created. type: array items: $ref: "#/definitions/Label" required: - adPlatformAccountId - campaignAdPlatformIds - labels AdPlatformMasterAccountResponse: type: object properties: adPlatformMasterAccount: $ref: "#/definitions/AdPlatformMasterAccount" BillingAccountResponse: type: object properties: billingAccounts: type: array items: $ref: "#/definitions/BillingAccount" BillingAccount: type: object properties: id: description: A 16 digit ID of the billing account. type: string example: 1234-5678-9012-3456 name: description: Name of the billing account. type: string example: Google Ads MCC currency: description: ISO 4217 [currency code](../../system-codes/#currency-codes). type: string example: CAD primaryBillingId: description: A 12 digit billing ID assigned to the user by Google. This must be passed in as a string with dashes. type: string example: 1234-5678-9012 AdPlatformMasterAccountsResponse: type: object properties: adPlatformMasterAccounts: type: array items: $ref: "#/definitions/AdPlatformMasterAccount" AdPlatformMasterAccount: type: object discriminator: type properties: type: type: string description: | OpenAPI discriminator. Value can be `GoogleAdsAdPlatformMasterAccount` or `MicrosoftAdvertisingAdPlatformMasterAccount`. id: description: ID of the Ad Platform master account. type: integer format: int64 example: 25 name: type: string description: Name of the Ad Platform master account. example: Google Ads MCC status: type: string description: | Status of the link between the Acquisio platform and the Ad Platform. When the status is `Pending` or `Invalid`, it means that the Acquisio platform can no longer access the master account through the Ad Platform API. | Values | |---------| | Active | | Invalid | | Pending | example: Active adPlatformType: type: string description: | Type of the Ad Platform account. | Values | |-----------------------| | GoogleAds | | MicrosoftAdvertising | linkedAdPlatformAccounts: type: array items: $ref: "#/definitions/AdPlatformAccount" AdPlatformManagedAccountsResponse: type: object properties: adPlatformManagedAccounts: type: array items: $ref: "#/definitions/AdPlatformManagedAccount" AdPlatformManagedAccount: type: object discriminator: type properties: type: type: string description: | OpenAPI discriminator. Value can be `GoogleAdsAdPlatformManagedAccount` or `MicrosoftAdvertsingAdPlatformManagedAccount`. adPlatformId: type: integer format: int64 description: | ID that identifies the managed customer account in the API provided by the Ad Platform. - In the Provisioning API, adPlatformId is associated to the field `adPlatformId` of the resource `AdPlatformAccount`. - In the Google Ads API, adPlatformId is the field `customerId` of the type `ManagedCustomer` in the ManagedCustomerService. example: 6238605114 adPlatformName: type: string description: | Name of the managed customer account in the API provided by the Ad Platform. - In the Google Ads API, adPlatformName is the field `name` of the type `ManagedCustomer` in the ManagedCustomerService. example: Account name accountIds: description: List of account IDs to which this Ad Platform account is linked to. type: array items: type: integer format: int64 example: [123, 456, 789] childrenAdPlatformIds: description: | List of Ad Platform account IDs under a manager account (currently only available for Google Ads). The list is null by default, unless requested with the embed query parameter (`&embed=childrenAdPlatformIds`). type: array items: type: integer format: int64 example: [123123123, 456456456, 789789789] childrenAccounts: description: | List of children of a manager account (currently only available for Google Ads). The list is null by default, unless requested with the embed query parameter (`&embed=childrenAccounts`). type: array items: $ref: "#/definitions/AdPlatformManagedAccount" example: - type: GoogleAdsAdPlatformManagedAccount adPlatformId: 123456 adPlatformName: name accountIds: [123, 456, 789] childrenAdPlatformIds: [123123123, 456456456, 789789789] childrenAccounts: [] GoogleAdsAdPlatformManagedAccount: type: object allOf: - $ref: "#/definitions/AdPlatformManagedAccount" MicrosoftAdvertisingAdPlatformManagedAccount: type: object allOf: - $ref: "#/definitions/AdPlatformManagedAccount" - type: object properties: adPlatformAccountNumber: type: string description: Account number that identifies the number of the Microsoft Advertising account example: A1234567 GoogleAdsAdPlatformMasterAccount: type: object allOf: - $ref: "#/definitions/AdPlatformMasterAccount" - type: object properties: adPlatformId: type: integer format: int64 description: | ID that identifies the Ad Platform master account in the API provided by the Ad Platform. `adPlatformId` can be null when `status` has a value of `Pending` or `Invalid`. example: 5554441212 MicrosoftAdvertisingAdPlatformMasterAccount: type: object allOf: - $ref: "#/definitions/AdPlatformMasterAccount" AdPlatformMasterResellerAccountResponse: type: object properties: adPlatformMasterResellerAccount: $ref: "#/definitions/AdPlatformMasterResellerAccount" AdPlatformMasterResellerAccountsResponse: type: object properties: adPlatformMasterResellerAccounts: type: array items: $ref: "#/definitions/AdPlatformMasterResellerAccount" AdPlatformMasterResellerAccount: type: object properties: id: description: ID of the Ad Platform master reseller account. type: integer format: int64 example: 25 name: type: string description: Name of the Ad Platform master reseller account. example: Microsft Advertising Reseller Account adPlatformApiToken: type: string description: | API token of the reseller account of the Ad Platform. example: JB1P9RQUL12 adPlatformCustomerId: type: string description: | Customer ID of the reseller account of the Ad Platform. example: 12022585 adPlatformType: type: string description: | Type of the Ad Platform account. | Values | |---------| | MicrosoftAdvertising | example: MicrosoftAdvertising contactFirstName: type: string description: Name of the contact's first name. example: Lauren contactLastName: type: string description: Name of the contact's last name. example: Smith addressLine1: type: string description: First line of the address on the master reseller account. example: 6300 Auteuil addressLine2: type: string description: Second line of the address on the master reseller account. example: Suite 300 city: type: string description: Name of the city of the address on the master reseller account. example: Brossard country: type: string description: Name of the country of the address on the master reseller account. example: CA postalCode: type: string description: Postal code of the address on the master reseller account. example: J4Z 3P2 stateProvince: type: string description: State or province of the address on the reseller account. example: QC AdPlatformAccount: type: object discriminator: type properties: type: type: string description: | OpenAPI discriminator. Value can be `GoogleAdsAdPlatformAccount`, `MicrosoftAdvertisingAdPlatformAccount` or `FacebookAdPlatformAccount`. id: description: ID of the Ad Platform account. type: integer format: int64 name: type: string description: Name of the Ad Platform account. example: Google Ads - Construction Inc. status: type: string description: | Status of the Ad Platform. | Values | |------------| | Deprecated | | ReadOnly | | ReadWrite | | Unlinked | example: ReadWrite adPlatformId: type: integer format: int64 description: | ID that identifies the customer account in the API provided by the Ad Platform. - In the Google Ads API, adPlatformId is the field `customerId` of the type `Customer` in the CustomerService. - In the Microsoft Advertising API, adPlatformId is the element `Number` of the data object `AccountInfo` in the Customer Management Service. example: 444-444-4445 accountId: type: integer format: int64 description: ID of the account. example: 123 currency: type: string description: | ISO 4217 [currency code](../../system-codes/#currency-codes). example: CAD adPlatformType: type: string description: | Type of the Ad Platform account. | Values | |------------------------| | Facebook | | GoogleAds | | MicrosoftAdvertising | example: GoogleAds isLoginValid: type: boolean description: | If `isLoginValid` is true, Acquisio can communicate with the Ad Platform to retrieve daily statistics, update campaigns, etc. If `isLoginValid` is `false` and `status` is `Unlinked`, an unlink operation was done with Provisioning API or by a Client Campaigns user. If `isLoginValid` is `false` and `status` isn't `Unlinked`, a password was changed or the login Acquisio had with the Ad Platform expired. If it's not intended, someone should relink the Ad Platform account with Provisioning API or the Client Campaigns UI. Value is from Client Campaign table providerAccount.isLoginValid GoogleAdsAdPlatformAccount: type: object allOf: - $ref: "#/definitions/AdPlatformAccount" - type: object properties: timeZone: description: Time zone of the Ad Platform account. It is an useful information for daily statistics. type: string example: America/Toronto MicrosoftAdvertisingAdPlatformAccount: type: object allOf: - $ref: "#/definitions/AdPlatformAccount" - type: object properties: adPlatformAccountNumber: description: Number of the Ad Platform account. type: string example: America/Toronto marketCountry: type: string description: | The primary country where the customer operates. For a list of customer market country code values, see [Country Codes](../../system-codes/#country-codes). example: CA marketLanguage: type: string description: | The primary language that the customer uses. Your customer market language determines the language of the Microsoft Advertising interface. The complete list of allowed [customer market language codes](https://msdn.microsoft.com/library/bing-ads-ad-languages.aspx#productlanguage) is available in the Microsoft Advertising API documentation. | Values | |--------------------| | Arabic | | Danish | | Dutch | | English | | Finnish | | French | | German | | Hebrew | | Italian | | Japanese | | Korean | | Norwegian | | Portuguese | | Russian | | SimplifiedChinese | | Spanish | | Swedish | | TraditionalChinese | example: English FacebookAdPlatformAccount: type: object allOf: - $ref: "#/definitions/AdPlatformAccount" Label: type: object properties: name: type: string description: | Unique name that identifies the label. minLength: 1 maxLength: 30 example: City value: type: string description: | The value of the label for a resource. minLength: 1 maxLength: 4000 example: Los Angeles required: - name - value LabelWithValues: type: object properties: name: type: string description: Name of the label. minLength: 1 maxLength: 30 example: City values: type: array description: Values associated to the name of the label. items: type: string minLength: 1 maxLength: 4000 example: [Montreal,Vancouver] LabelsResponse: type: object properties: labels: type: array items: $ref: "#/definitions/LabelWithValues" ResourceLabelsResponse: type: object properties: resourceLabels: type: array items: $ref: "#/definitions/ResourceLabels" ResourceLabels: type: object properties: name: type: string description: Name of the resource (account name or campaign name). example: Bob's Account id: type: integer format: int64 description: ID of the resource (account ID or campaign ID). example: 123 labels: type: array items: $ref: "#/definitions/ResourceLabel" BulkEditResourceLabelsRequest: type: object properties: resourceLabels: type: array items: $ref: "#/definitions/ResourceLabelsRequest" ResourceLabelsRequest: type: object properties: id: type: integer format: int64 description: ID of the resource (account ID or campaign ID). example: 123 labels: type: array items: $ref: "#/definitions/ResourceLabel" ResourceLabel: type: object properties: id: type: integer format: int64 description: ID of the label. example: 123 name: type: string description: | Unique name that identifies the label. minLength: 1 maxLength: 80 example: Color value: type: string description: | The value of the label for this resource. minLength: 1 maxLength: 120 example: Red required: - name - value LabelNameUpdateContainer: type: object properties: label: $ref: "#/definitions/LabelName" LabelName: type: object properties: name: type: string description: Name of the label. minLength: 1 maxLength: 30 JobsResponse: type: object properties: jobs: type: array items: $ref: "#/definitions/Job" JobResponse: type: object properties: job: $ref: "#/definitions/Job" Job: type: object discriminator: type properties: type: type: string description: | OpenAPI discriminator. Value can be `ParentJob`, `DeleteJob`, `ImportCampaignJob`, `CloneCampaignJob`, `UnlinkJob`. id: type: integer format: int64 description: | ID of the job. example: 105 description: type: string description: Short description of the job. example: Deleting Ad Platform accounts. status: type: string description: | Status of the job. | Values | |-------------| | Aborted | | Completed | | Incomplete | | Running | | UnderReview | example: Running createdDate: type: string format: date-time description: Date of the creation of the job in an ISO 8601 format in UTC. example: 2017-09-21T16:45:03Z finishedDate: type: string format: date-time description: Date of the completion of the job in an ISO 8601 format in UTC. example: 2017-09-21T16:52:56Z ParentJob: description: Parent job allOf: - $ref: "#/definitions/Job" - type: object properties: childJobs: type: array description: List of child jobs. items: $ref: "#/definitions/Job" DeleteJob: description: Delete job allOf: - $ref: "#/definitions/Job" - type: object properties: entityId: type: integer description: Id of the entity that is deleted. format: int64 example: 300 entityLevel: type: string description: | Entity level | Values | |-------------------| | Account | | AdPlatformAccount | example: AdPlatformAccount UnlinkJob: description: Unlink job allOf: - $ref: "#/definitions/Job" - type: object properties: entityId: type: integer description: ID of the entity that is unlinked. format: int64 example: 300 entityLevel: type: string description: | Entity level | Values | |------------------| | Campaign | example: Campaign CloneCampaignJob: description: Clone campaign job allOf: - $ref: "#/definitions/Job" - type: object properties: accountId: type: integer description: ID of the account. format: int64 example: 300 accountName: type: string description: Name of the account. example: Guitars NYC adPlatformAccountId: type: integer description: ID of the Ad Platform account. format: int64 example: 300 adPlatformAccountName: type: string description: Name of the Ad Platform. example: Guitars NYC adPlatformType: type: string description: | Ad Platform type | Values | |------------------------| | Facebook | | GoogleAds | | MicrosoftAdvertising | example: GoogleAds ImportCampaignJob: description: Import campaign job allOf: - $ref: "#/definitions/Job" - type: object properties: accountId: type: integer description: ID of the account. format: int64 example: 300 accountName: type: string description: Name of the account. example: Guitars NYC adPlatformAccountId: type: integer description: ID of the Ad Platform account. format: int64 example: 300 adPlatformAccountName: type: string description: Name of the Ad Platform. example: Guitars NYC adPlatformType: type: string description: | Ad Platform type | Values | |-----------------------| | Facebook | | GoogleAds | | MicrosoftAdvertising | example: GoogleAds