ADvendio v1.4
API docs by Redocly

Custom Media Integration Callback API (CMI) (1.4)

The endpoints you build so that ADvendio can book, forecast, report and synchronize with your ad server.

Introduction

The Custom Media Integration (CMI) Callback API connects external advertising platforms with ADvendio. It manages campaigns, inventory, forecasting, reporting and status synchronization in both directions.

CMI is a callback API: you build the endpoints described here, and ADvendio calls them. For each operation, the ADvendio Gateway sends an HTTP POST request with a JSON body to your web service. Your service performs the operation in your ad server and returns the result in the CMI format.

  1. A user runs a job in ADvendio, for example a booking, a forecast or a delivery report.
  2. The ADvendio Gateway sends a POST request to the Custom Endpoint of the Connection plus the operation path, for example https://yourdomain.com/api/cmi/selling.
  3. Your service applies the request in your ad server and returns a JSON response.
  4. ADvendio saves the result in Salesforce. The request and the response are visible in the Log Viewer.

Key features

  • Connection Check: secure authentication and connection testing with external systems.
  • Ad Server Entity Retrieval: retrieve targeting options, inventory and advertising entities.
  • Buying: create and manage advertising campaigns, orders and line items.
  • Selling: manage advertising inventory sales and placements.
  • Forecast: predict inventory availability and identify competing advertisements.
  • Reporting: generate performance reports with custom metrics.
  • Status Synchronization: status updates in both directions.
  • Wallet: synchronize budgets and spending between Salesforce and your ad server.
  • Campaign Import: import campaigns and line items from your ad server into Salesforce.

Troubleshooting

The Log Viewer shows exactly what happens when your jobs communicate with your custom media integration. It records every request and response between ADvendio and your service, which makes it much easier to troubleshoot issues:

  • A complete conversation history between ADvendio and your platform.
  • Faster debugging, with all the necessary details.
  • Insight into API behavior and response patterns.
  • An audit trail for compliance and troubleshooting.

See Log Viewer for how to use it.

Changelog

ADvendio version Date Section Change
Documentation update November 2026 All OpenAPI 3.1 version of the documentation (version 1.4). Corrected the examples to match the field descriptions: status values, booleans, targeting structure, custom field keys, custom metrics and wallet associations. Added the request and response envelope, the authentication schemes and the exact endpoint paths.
Documentation update November 2026 Connection Check, Log Viewer Clarified: the Connection sends its Network Time Zone in the key timezone of customEntitySettings. The Log Viewer masks the values of the listed field names, and replaces a number or boolean with null.
Documentation update November 2026 Buying, Selling, FAQ Corrected: the response fields are named itemNew, orderNew and advertiserNew, without the "is" prefix. A response that uses the "is" names is accepted, but the flags have no effect.
Documentation update October 2026 Targeting Clarified: logicOperator and type values, how targeting is defined and sent.
Documentation update October 2026 Log Viewer, Best Practices Clarified: redaction marker, API key headers, timeouts, no retries and no paging requests from ADvendio.
Documentation update October 2026 Reporting Clarified: periodId is the Salesforce ID of the custom fiscal period. Added request and response examples with and without custom fiscal periods.
Documentation update October 2026 Campaign Import Clarified: the import mode was removed. The import always returns the campaigns that match the date range and campaign status filters.
Documentation update October 2026 Ad Server Entities, Forecast Clarified: documented the typeId request field and the contendingAds response field.
Documentation update October 2026 Getting started Clarified: the example endpoint is /cmi/selling, and the login, forecast, report, statussync, walletpush and walletpull paths end with a slash.
Documentation update October 2026 Getting started Corrected: the label of the Connection record type is Custom Media Integration (CMI). The API name remains CustomMediaIntegration.
2.186 2026-10-29 Campaign Import New: optional request field adServerAccountId. When accounts are assigned to the Connection, ADvendio sends one Campaign Import request for each account.
2.186 2026-10-29 Campaign Import New: the key dateSemantics with the value INSTANT in the customEntitySettings of a campaign. ADvendio then converts the start and end dates of the campaign and its items to the Network Time Zone of the Connection.
2.186 2026-10-29 Ad Server Entities, Custom Fields New: Connection ID custom fields are requested in customRequestSettings of the Ad Server Entity Retrieval and returned in the customEntitySettings of each entity.
2.186 2026-10-29 Selling Changed: budgetType is the Budget Type of the Campaign Item as saved in Salesforce, so custom values are possible. It was a fixed list of values before.
2.186 2026-10-29 Wallet New: the wallet field isManaged. ADvendio sends it in Wallet Push and Wallet Pull requests and saves the value that the response returns.
2.186 2026-10-29 Forecast, Custom Fields Changed: custom fields are now also sent with forecast requests, in the customEntitySettings of each item (see 13). The campaign custom fields are sent on each item together with the item custom fields.
2.186 2026-10-29 Custom Fields Changed: optional third key part ({idString}) when the custom field mapping in ADvendio has an ad server field ID.
2.183 2026-07-07 Campaign Import New: Campaign Import operation (/cmi/import/selling).
2.182 2026-04-09 Wallet New: Wallet Push (/cmi/walletpush/) and Wallet Pull (/cmi/walletpull/).
2.180 October 2025 All Initial version of the CMI documentation.

Getting started

Prerequisites

  • ADvendio version 2.180 or higher.
  • License: ADvendio One.
  • Access: Salesforce admin rights to create and configure objects and fields.

Create the Connection record

  1. In Salesforce, go to the Connection object (ADvendio__AdServer_Logins__c).
  2. Create a new record and set the Record Type to Custom Media Integration (CMI). The API name of the record type is CustomMediaIntegration.
  3. In the Custom Endpoint field, enter the base URL of your web service, for example https://yourdomain.com/api.

Develop your web service endpoints

Your service must expose one endpoint for each CMI operation. Each endpoint accepts HTTP POST requests with a JSON body and returns JSON in the CMI format. ADvendio appends the operation path to your Custom Endpoint.

Use the paths exactly as listed. The login, forecast, report, statussync, walletpush and walletpull paths end with a slash.

Operation Endpoint Response media type ADvendio waits at most
Connection Check POST /cmi/login/ application/json 5 minutes
Ad Server Entity Retrieval POST /cmi/adserverentities application/stream+json 30 minutes
Buying POST /cmi/buying application/json 5 minutes
Selling (booking) POST /cmi/selling application/json 5 minutes
Forecast POST /cmi/forecast/ application/json 5 minutes
Report POST /cmi/report/ application/json 60 minutes
Status Sync POST /cmi/statussync/ application/json 5 minutes
Wallet Push POST /cmi/walletpush/ application/json 30 minutes
Wallet Pull POST /cmi/walletpull/ application/json 30 minutes
Campaign Import POST /cmi/import/selling application/stream+json 30 minutes

Example: with the Custom Endpoint https://yourdomain.com/api, ADvendio calls POST https://yourdomain.com/api/cmi/login/, POST https://yourdomain.com/api/cmi/report/ and POST https://yourdomain.com/api/cmi/selling.

Set up your API key

The Media Integration API Key Generation button on Custom Media Integration Connection records creates and manages the API key that ADvendio sends to your endpoints.

  1. Open the component. A modal shows a description and two buttons: Cancel and Generate API Key.
  2. Click Generate API Key to create a new authentication token for the Connection.
  3. The new API key is shown in a read-only text field. Click Copy to copy it to your clipboard for use in your system. A warning reminds you to store the key securely.

See Authentication for how ADvendio sends the key.

Test connectivity

Implement the Connection Check endpoint (/cmi/login/) first to validate the credentials. See also Best Practices.

Conventions

Requests

  • ADvendio sends every request as an HTTP POST with a JSON body (Content-Type: application/json) over HTTPS.
  • Every request body contains the same envelope: connection (the Connection record, with the credentials and the endpoint), orgId (the Salesforce org ID) and customRequestSettings (additional key-value settings). See the CmiRequest schema in any operation.
  • Fields without a value are sent as null.
  • New ADvendio versions can add optional fields (see the Changelog). Ignore fields that you do not know instead of rejecting the request.

Responses

  • Return HTTP 200 with a JSON body in the CMI format. Set status to SUCCESS or ERROR and describe the result in message.
  • For bulk operations, set successCount and failureCount, and report the result of each entity in the response units, with errors, warnings and infoMessages.
  • Return the complete result in one response. ADvendio does not request further pages: the paging fields (currentPage, pageSize, totalElements, totalPages, hasNext, hasPrevious, isFirst, isLast) are informational.
  • ADvendio does not retry a failed call. It waits at most 5 minutes for login, booking, buying, forecast and status sync, 30 minutes for entity import, campaign import and wallet, and 60 minutes for reports.

Streaming responses

Ad Server Entity Retrieval and Campaign Import return a stream of JSON objects with the media type application/stream+json: one complete JSON object per line, without an enclosing array and without commas between the objects. The response schema of these operations describes one object of the stream.

Data types

Type in the field descriptions JSON
String string
Integer, Long integer (int32, int64)
Double, Float, BigDecimal number
Boolean true or false
ZonedDateTime string, ISO 8601 date-time with offset, for example 2025-10-06T14:23:45.123-04:00
LocalDate string, ISO 8601 date, for example 2024-06-01
Map<String, String> object whose values are strings
List array

The values of customEntitySettings, customRequestSettings and customResponseSettings are always strings, also for numbers and booleans (for example "true").

Authentication

Every request is sent over HTTPS and carries the API key generated on the Connection (see Set up your API key). ADvendio sends the same key in three places:

  • the X-API-Key header,
  • the Authorization header, as a Bearer token,
  • the connection.token field of the request body.

Validate the key in your endpoint, or in an API gateway in front of it. If you need OAuth, handle OAuth for your own systems there. Do not send the API key back in a response header.

ApiKeyHeader

The API key generated on the Connection record. ADvendio sends it in the X-API-Key header of every request.

Security Scheme Type: API Key
Header parameter name: X-API-Key

BearerAuth

The same API key, sent as a Bearer token in the Authorization header of every request.

Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer

Connection Check

Validate the connection to your system.

Check the connection

Validates the connection to your system (also called Check Login). Implement this endpoint first.

Validate the API key of the request (see Authentication), then check that your service can reach your ad server with the credentials of the connection. Return connectionStatus CONNECTED on success. If your ad server rejects the credentials, return HTTP 200 with status ERROR, the matching connectionStatus (for example UNAUTHORIZED) and the details in errors.

When the Connection record has a Network Time Zone, ADvendio sends it in the key timezone of connection.customEntitySettings, as a time zone ID, for example Europe/Berlin.

Timeout: ADvendio waits at most 5 minutes for the response.

Authorizations:
ApiKeyHeaderBearerAuth
Request Body schema: application/json
required
required
object (Connection)

Connection details for the target external system. Contains authentication credentials, endpoints, and connection configuration required to communicate with ad servers or other integrated systems.

orgId
required
string

Salesforce organization ID of the request context. Used to scope operations to the appropriate organizational unit and ensure proper data isolation and access control.

object or null

Custom request settings as key-value pairs. Allows for flexible configuration and extension of request properties without modifying the core request structure. Can include feature flags, processing options, or integration-specific parameters.

Responses

Response Schema: application/json
status
required
string
Enum: "SUCCESS" "ERROR"

Overall status of the operation. "SUCCESS" or "ERROR"

message
string or null

Descriptive message about the operation result. Provides additional context about the status, error details, or success information.

successCount
integer or null <int32>

Number of successfully processed operations. Used in bulk operations to indicate how many items were processed successfully.

failureCount
integer or null <int32>

Number of failed operations. Used in bulk operations to indicate how many items failed processing.

object or null

Custom response settings as key-value pairs. Allows for flexible extension of response properties without modifying the core response structure. Can include processing metadata, debug information, or integration-specific data.

connectionStatus
string or null
Enum: "CONNECTED" "FAILED" "EXPIRED" "TIMEOUT" "UNAUTHORIZED" "UNAVAILABLE" null

Status of the connection to your system: CONNECTED, FAILED, EXPIRED, TIMEOUT, UNAUTHORIZED or UNAVAILABLE.

connectedAt
string or null <date-time>

Timestamp when the connection was successfully established. Records the exact date and time when the connection was successfully made to the external system.

expiresAt
string or null <date-time>

Timestamp when the connection or authentication token expires. For token-based authentication systems, this indicates when the current authentication will expire and need to be renewed. For session-based connections, this represents the session timeout period. May be null for connections that do not have explicit expiration times or for failed connection attempts.

errors
Array of strings or null

List of connection-specific error messages. Contains detailed error information specific to connection operations, such as network connectivity errors, authentication failures, SSL/TLS certificate issues, endpoint configuration problems, API version compatibility issues, rate limiting or quota exceeded messages.

Request samples

Content type
application/json
{
  • "connection": {
    • "salesforceId": "a0X5g000001234ABC",
    • "id": "ext-adserver-001",
    • "name": "Production Ad Server Connection",
    • "customEntitySettings": { },
    • "connectionType": "CustomMediaIntegration",
    • "username": "api_user@company.com",
    • "password": "SecurePassword123!",
    • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
    • "endpoint": "https://api.adserver.com/v1"
    },
  • "orgId": "00D5g000001AbCdEFG",
  • "customRequestSettings": { }
}

Response samples

Content type
application/json
Example
{
  • "status": "SUCCESS",
  • "message": "Connection test completed successfully.",
  • "successCount": 1,
  • "failureCount": 0,
  • "customResponseSettings": { },
  • "connectionStatus": "CONNECTED",
  • "connectedAt": "2025-10-06T14:23:45.123-04:00",
  • "expiresAt": "2025-10-06T16:23:45.123-04:00",
  • "errors": [ ]
}

Ad Server Entities

Import targeting options, inventory and other entities of your ad server as Connection IDs.

Retrieve ad server entities

Returns the entities of your ad server, such as targeting segments, inventory sources and geographic locations. ADvendio imports them as Connection IDs (ADvendio__AdServer_ID__c) of the Connection.

The response must be a stream of AdServerEntity objects with the media type application/stream+json: one JSON object per line.

  • The stream is controlled by the ADvendio Gateway. Do not set server-side timeouts or flow controls.
  • Stream the entities of the same type together. Each time an entity with a different type is sent, the Gateway starts a flush process that pushes all Connection IDs held in memory to Salesforce.
  • Each entity must define a type. By default, all entities are standard Connection IDs. An entity with the type ERROR is an error message from your server.
  • From version 2.186, customRequestSettings can request custom fields of the Connection IDs. Return them in the customEntitySettings of each entity (see Connection ID custom fields).

Example of a complete response with two cities of Germany (one JSON object per line):

{"salesforceId":null,"id":"6923483","name":"Berlin","customEntitySettings":null,"errors":null,"warnings":null,"category":"Geography","type":"City","status":"ACTIVE","start":"2025-10-06T14:23:45.123-04:00","end":"2025-11-06T14:23:45.123-04:00","parent":{"salesforceId":null,"id":"76309","name":"Germany","customEntitySettings":null,"errors":null,"warnings":null,"category":"Geography","type":"Country","status":"ACTIVE","start":"2025-10-06T14:23:45.123-04:00","end":"2025-11-06T14:23:45.123-04:00"}}
{"salesforceId":null,"id":"6922480","name":"Hamburg","customEntitySettings":null,"errors":null,"warnings":null,"category":"Geography","type":"City","status":"ACTIVE","start":"2025-10-06T14:23:45.123-04:00","end":"2025-11-06T14:23:45.123-04:00","parent":{"salesforceId":null,"id":"76309","name":"Germany","customEntitySettings":null,"errors":null,"warnings":null,"category":"Geography","type":"Country","status":"ACTIVE","start":"2025-10-06T14:23:45.123-04:00","end":"2025-11-06T14:23:45.123-04:00"}}

Timeout: ADvendio waits at most 30 minutes for the response.

Authorizations:
ApiKeyHeaderBearerAuth
Request Body schema: application/json
required
required
object (Connection)

Connection details for the target external system. Contains authentication credentials, endpoints, and connection configuration required to communicate with ad servers or other integrated systems.

orgId
required
string

Salesforce organization ID of the request context. Used to scope operations to the appropriate organizational unit and ensure proper data isolation and access control.

object or null

Custom request settings as key-value pairs. Allows for flexible configuration and extension of request properties without modifying the core request structure. Can include feature flags, processing options, or integration-specific parameters.

category
string or null
Examples: "Geography"

Category filter for entity classification. Filters entities by their category classification, enabling retrieval of entities within specific categorical groupings. For the supported categories, see the Appendix.

types
Array of strings or null

Entity type filter. Limits the query to entities of specific types. When types is null or empty, the user in the ADvendio UI selected all the types of the category, or just the category itself: return the AdServerEntities of all types contained in the category. For the supported types, see the Appendix.

typeId
string or null
Examples: "76309"

Optional filter: the ID of a parent entity or subtype. When set, return only the entities below it, for example all cities of one country. When null, return all entities of the requested types.

Responses

Response Schema: application/stream+json
id
required
string or null

The ad server ID for this entity. This is the primary identifier used by the external ad server system.

type
required
string
Examples: "City"

Type of the ad server entity, for example Advertiser, Country, City, Ad Unit or Audience Segment (see the Appendix). Each entity must define a type. The special type ERROR marks the line as an error message from your server instead of an entity.

salesforceId
string or null

The Salesforce ID for this entity. Used to link entities back to their corresponding Salesforce records.

name
string or null

The ad server name for this entity. Human-readable name used by the external ad server system.

object or null

Custom entity settings as key-value pairs. Allows for flexible configuration and extension of entity properties without modifying the core data structure. The values are always strings. See Custom Fields.

errors
Array of strings or null

List of error messages associated with this entity. Used to report validation errors, processing errors, or system errors encountered during entity operations.

warnings
Array of strings or null

List of warning messages associated with this entity. Used to report non-fatal issues or important notifications that don't prevent processing but should be noted.

category
string or null
Examples: "Geography"

Category of the entity, for example Geography, Inventory or Accounts (see the Appendix).

status
string or null

Current status of the ad server entity, for example ACTIVE or INACTIVE. ADvendio saves it in the Status field of the Connection ID.

AdServerEntity (any) or null

Parent entity in hierarchical relationships, for example Country → State → City or Site → Placement. Leave it out (or null) for a top-level entity.

start
string or null <date-time>

Entity start date and time. Defines when this entity becomes active or available for use. Relevant for time-sensitive entities.

end
string or null <date-time>

Entity end date and time. Defines when this entity expires or becomes unavailable. Important for managing time-bound entities.

Request samples

Content type
application/json
Example
{
  • "connection": {
    • "salesforceId": "a0X5g000001234ABC",
    • "id": "ext-adserver-001",
    • "name": "Production Ad Server Connection",
    • "connectionType": "CustomMediaIntegration",
    • "username": "api_user@company.com",
    • "password": "SecurePassword123!",
    • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
    • "endpoint": "https://api.adserver.com/v1"
    },
  • "orgId": "00D5g000001AbCdEFG",
  • "customRequestSettings": { },
  • "category": "Geography",
  • "types": [
    • "City"
    ],
  • "typeId": "76309"
}

Response samples

Content type
application/stream+json
Example
{
  • "salesforceId": null,
  • "id": "6923483",
  • "name": "Berlin",
  • "customEntitySettings": null,
  • "errors": null,
  • "warnings": null,
  • "category": "Geography",
  • "type": "City",
  • "status": "ACTIVE",
  • "start": "2025-10-06T14:23:45.123-04:00",
  • "end": "2025-11-06T14:23:45.123-04:00",
  • "parent": {
    • "salesforceId": null,
    • "id": "76309",
    • "name": "Germany",
    • "customEntitySettings": null,
    • "errors": null,
    • "warnings": null,
    • "category": "Geography",
    • "type": "Country",
    • "status": "ACTIVE",
    • "start": "2025-10-06T14:23:45.123-04:00",
    • "end": "2025-11-06T14:23:45.123-04:00"
    }
}

Buying

Create and manage advertising campaigns, orders and line items for purchasing advertising inventory.

Submit buying campaigns, orders and items

Creates or updates advertising campaigns, orders and line items in your platform.

Buying operations follow a hierarchy:

  • BuyingCampaign: top-level container for strategic buying initiatives. This level is optional.
  • BuyingOrder: intermediate container for related line items.
  • BuyingItem: individual line item with specific targeting and bidding.

A request contains either campaigns (campaign level) or orders (order level), never both.

Return one response unit per processed component with submittedStatus Created, Updated or Failed.

Targeting: The targeting that ADvendio sends with a BuyingItem is limited to what is defined in the ad server targeting on the buying order or item. Every target in targetingCriteria is an ad server entity that ADvendio holds for the Connection, normally imported through Ad Server Entity Retrieval. Only the targeting of the item itself is sent, not the targeting of the order. Frequency capping and the target platform are not ad server entities: they are sent in the frequencyCapping and targetPlatform fields of the BuyingItem. See Targeting.

Timeout: ADvendio waits at most 5 minutes for the response.

Authorizations:
ApiKeyHeaderBearerAuth
Request Body schema: application/json
required
required
object (Connection)

Connection details for the target external system. Contains authentication credentials, endpoints, and connection configuration required to communicate with ad servers or other integrated systems.

orgId
required
string

Salesforce organization ID of the request context. Used to scope operations to the appropriate organizational unit and ensure proper data isolation and access control.

object or null

Custom request settings as key-value pairs. Allows for flexible configuration and extension of request properties without modifying the core request structure. Can include feature flags, processing options, or integration-specific parameters.

Array of objects or null (BuyingCampaign)

List of buying campaigns to be processed. When campaigns are included, the request operates at the campaign level, processing campaigns along with their associated orders and line items. This is typically used for comprehensive campaign management operations.

Array of objects or null (BuyingOrder)

List of buying orders to be processed. When orders are included without campaigns, the request operates at the order level, processing individual orders and their line items. This is typically used for order-specific operations or when campaigns are managed separately. Campaigns and orders are not sent in the same request.

Responses

Response Schema: application/json
status
required
string
Enum: "SUCCESS" "ERROR"

Overall status of the operation. "SUCCESS" or "ERROR"

message
string or null

Descriptive message about the operation result. Provides additional context about the status, error details, or success information.

successCount
integer or null <int32>

Number of successfully processed operations. Used in bulk operations to indicate how many items were processed successfully.

failureCount
integer or null <int32>

Number of failed operations. Used in bulk operations to indicate how many items failed processing.

object or null

Custom response settings as key-value pairs. Allows for flexible extension of response properties without modifying the core response structure. Can include processing metadata, debug information, or integration-specific data.

currentPage
integer or null <int32>

Current page number for paginated responses. Can be 0-based or 1-based depending on the implementation.

pageSize
integer or null <int32>

Number of items per page in paginated responses. Indicates the page size used for this response.

totalElements
integer or null <int64>

Total number of items across all pages. Provides the complete count of items available, not just those in the current page.

totalPages
integer or null <int32>

Total number of pages available. Calculated based on totalElements and pageSize.

hasNext
boolean or null

Indicates whether there is a next page available. Useful for navigation in paginated results.

hasPrevious
boolean or null

Indicates whether there is a previous page available. Useful for navigation in paginated results.

isFirst
boolean or null

Indicates whether this is the first page. Useful for UI rendering and navigation logic.

isLast
boolean or null

Indicates whether this is the last page. Useful for UI rendering and navigation logic.

Array of objects or null (BuyingResponseUnit)

List of individual response units for buying operations. Each unit in this list represents the processing result for a specific buying component (campaign, order, or line item). The units provide detailed information about operation outcomes, including success status, error messages, and custom field values.

Request samples

Content type
application/json
Example
{
  • "connection": {
    • "salesforceId": "a0X5g000001234ABC",
    • "id": "ext-adserver-001",
    • "name": "Production Ad Server Connection",
    • "connectionType": "CustomMediaIntegration",
    • "username": "api_user@company.com",
    • "password": "SecurePassword123!",
    • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
    • "endpoint": "https://api.adserver.com/v1"
    },
  • "orgId": "00D5g000001AbCdEFG",
  • "campaigns": [
    • {
      }
    ],
  • "orders": null
}

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Processed 1 campaign with 2 orders and 3 line items: 5 succeeded, 1 failed",
  • "successCount": 5,
  • "failureCount": 1,
  • "currentPage": 0,
  • "pageSize": 100,
  • "totalElements": 6,
  • "totalPages": 1,
  • "hasNext": false,
  • "hasPrevious": false,
  • "isFirst": true,
  • "isLast": true,
  • "buyingResponses": [
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ]
}

Selling

Book advertising inventory: orders (Media Campaigns) and their items (Campaign Items).

Book selling orders and items

Books advertising inventory: creates or updates the orders (Media Campaigns) and their items (Campaign Items) in your ad server.

Return one response unit per Campaign Item with salesforceId, id and orderId. ADvendio saves id and orderId as the ad server IDs of the item and of its order. Set itemNew, orderNew or advertiserNew to true when the item, the order or the advertiser was created, so that ADvendio updates the ad server IDs.

Targeting: The targeting that ADvendio sends with a SellingItem is limited to what is defined in the ad server targeting on the Campaign Item. Every target in targetingCriteria is an ad server entity that ADvendio holds for the Connection, normally imported through Ad Server Entity Retrieval. Day and time targeting and frequency capping are not ad server entities: they are sent in the dayTimeTargeting and frequencyCapping fields of the SellingItem. See Targeting.

Timeout: ADvendio waits at most 5 minutes for the response.

Authorizations:
ApiKeyHeaderBearerAuth
Request Body schema: application/json
required
required
object (Connection)

Connection details for the target external system. Contains authentication credentials, endpoints, and connection configuration required to communicate with ad servers or other integrated systems.

orgId
required
string

Salesforce organization ID of the request context. Used to scope operations to the appropriate organizational unit and ensure proper data isolation and access control.

object or null

Custom request settings as key-value pairs. Allows for flexible configuration and extension of request properties without modifying the core request structure. Can include feature flags, processing options, or integration-specific parameters.

Array of objects or null (SellingOrder)

List of selling orders to be processed. Each order in this list represents a complete inventory sale commitment including advertiser details, billing information, budget allocation, and associated line items. The request processes these orders for creation, modification, or status updates in the inventory management system.

Responses

Response Schema: application/json
status
required
string
Enum: "SUCCESS" "ERROR"

Overall status of the operation. "SUCCESS" or "ERROR"

message
string or null

Descriptive message about the operation result. Provides additional context about the status, error details, or success information.

successCount
integer or null <int32>

Number of successfully processed operations. Used in bulk operations to indicate how many items were processed successfully.

failureCount
integer or null <int32>

Number of failed operations. Used in bulk operations to indicate how many items failed processing.

object or null

Custom response settings as key-value pairs. Allows for flexible extension of response properties without modifying the core response structure. Can include processing metadata, debug information, or integration-specific data.

currentPage
integer or null <int32>

Current page number for paginated responses. Can be 0-based or 1-based depending on the implementation.

pageSize
integer or null <int32>

Number of items per page in paginated responses. Indicates the page size used for this response.

totalElements
integer or null <int64>

Total number of items across all pages. Provides the complete count of items available, not just those in the current page.

totalPages
integer or null <int32>

Total number of pages available. Calculated based on totalElements and pageSize.

hasNext
boolean or null

Indicates whether there is a next page available. Useful for navigation in paginated results.

hasPrevious
boolean or null

Indicates whether there is a previous page available. Useful for navigation in paginated results.

isFirst
boolean or null

Indicates whether this is the first page. Useful for UI rendering and navigation logic.

isLast
boolean or null

Indicates whether this is the last page. Useful for UI rendering and navigation logic.

Array of objects or null (SellingResponseUnit)

List of individual response units for selling operations. Each unit in this list represents the processing result for a specific selling component (order or line item). The units provide detailed information about operation outcomes, including success status, error messages, and custom field values for inventory management tracking.

Request samples

Content type
application/json
{
  • "connection": {
    • "salesforceId": "a0X5g000001234ABC",
    • "id": "ext-adserver-001",
    • "name": "Production Ad Server Connection",
    • "connectionType": "CustomMediaIntegration",
    • "username": "api_user@company.com",
    • "password": "SecurePassword123!",
    • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
    • "endpoint": "https://api.adserver.com/v1"
    },
  • "orgId": "00D5g000001AbCdEFG",
  • "orders": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Successfully processed 3 line items in 2 selling orders",
  • "successCount": 3,
  • "failureCount": 0,
  • "customResponseSettings": {
    • "processingTime": "1876ms",
    • "adServerVersion": "v2.4.1",
    • "inventoryCheckCompleted": "true"
    },
  • "currentPage": 0,
  • "pageSize": 100,
  • "totalElements": 3,
  • "totalPages": 1,
  • "hasNext": false,
  • "hasPrevious": false,
  • "isFirst": true,
  • "isLast": true,
  • "sellingResponses": [
    • {
      },
    • {
      },
    • {
      }
    ]
}

Forecast

Predict inventory availability and identify competing advertisements.

Forecast inventory availability

Predicts inventory availability and identifies competing advertisements for each selling item:

  • available inventory for the requested targeting and timing,
  • competing advertisements that may contend for the same inventory,
  • booking potential and delivery probability,
  • inventory conflicts and optimization opportunities.

Return one ForecastResponseUnit per item of the request, in the same order.

Custom fields: each item carries its custom fields in customEntitySettings, in the same key format as a selling request (see Custom Fields). The forecast request has no order level, so the campaign (order) custom fields are sent on each item together with the item custom fields. A custom field is sent only if it has a value in ADvendio. Items of a campaign that has not been saved in Salesforce yet are sent without custom fields.

Timeout: ADvendio waits at most 5 minutes for the response.

Authorizations:
ApiKeyHeaderBearerAuth
Request Body schema: application/json
required
required
object (Connection)

Connection details for the target external system. Contains authentication credentials, endpoints, and connection configuration required to communicate with ad servers or other integrated systems.

orgId
required
string

Salesforce organization ID of the request context. Used to scope operations to the appropriate organizational unit and ensure proper data isolation and access control.

object or null

Custom request settings as key-value pairs. Allows for flexible configuration and extension of request properties without modifying the core request structure. Can include feature flags, processing options, or integration-specific parameters.

Array of objects or null (SellingItem)

Selling items to be forecast. Each item is a proposed advertising placement; analyze its targeting criteria, timing, pricing and inventory requirements to determine availability and potential conflicts. Each item carries its custom fields, and those of its campaign, in customEntitySettings (see Custom Fields).

Responses

Response Schema: application/json
status
required
string
Enum: "SUCCESS" "ERROR"

Overall status of the operation. "SUCCESS" or "ERROR"

message
string or null

Descriptive message about the operation result. Provides additional context about the status, error details, or success information.

successCount
integer or null <int32>

Number of successfully processed operations. Used in bulk operations to indicate how many items were processed successfully.

failureCount
integer or null <int32>

Number of failed operations. Used in bulk operations to indicate how many items failed processing.

object or null

Custom response settings as key-value pairs. Allows for flexible extension of response properties without modifying the core response structure. Can include processing metadata, debug information, or integration-specific data.

currentPage
integer or null <int32>

Current page number for paginated responses. Can be 0-based or 1-based depending on the implementation.

pageSize
integer or null <int32>

Number of items per page in paginated responses. Indicates the page size used for this response.

totalElements
integer or null <int64>

Total number of items across all pages. Provides the complete count of items available, not just those in the current page.

totalPages
integer or null <int32>

Total number of pages available. Calculated based on totalElements and pageSize.

hasNext
boolean or null

Indicates whether there is a next page available. Useful for navigation in paginated results.

hasPrevious
boolean or null

Indicates whether there is a previous page available. Useful for navigation in paginated results.

isFirst
boolean or null

Indicates whether this is the first page. Useful for UI rendering and navigation logic.

isLast
boolean or null

Indicates whether this is the last page. Useful for UI rendering and navigation logic.

Array of objects or null (ForecastResponseUnit)

One forecast result per selling item of the request, in the same order. Each unit gives the available, matching and booked inventory and the competing advertisements.

Request samples

Content type
application/json
{
  • "connection": {
    • "salesforceId": "a0X5g000001234ABC",
    • "id": "ext-adserver-001",
    • "name": "Production Ad Server Connection",
    • "connectionType": "CustomMediaIntegration",
    • "username": "api_user@company.com",
    • "password": "SecurePassword123!",
    • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
    • "endpoint": "https://api.adserver.com/v1"
    },
  • "orgId": "00D5g000001AbCdEFG",
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Successfully forecasted 1 selling item",
  • "successCount": 1,
  • "failureCount": 0,
  • "currentPage": 0,
  • "pageSize": 100,
  • "totalElements": 1,
  • "totalPages": 1,
  • "hasNext": false,
  • "hasPrevious": false,
  • "isFirst": true,
  • "isLast": true,
  • "forecastResponses": [
    • {
      }
    ]
}

Reporting

Performance reports with standard and custom metrics.

Get delivery and performance metrics

Returns performance metrics, with standard and custom metrics, for the advertisements of the request.

  • reportType: SELLING (performance metrics for sold advertising inventory) or BUYING (performance metrics for purchased advertising campaigns).
  • reportInterval: TOTAL (aggregated data across all time periods), MONTHLY (data grouped by month) or DAILY (data grouped by day).

Custom fiscal periods. When the org uses custom fiscal periods, periodId is the Salesforce ID of the fiscal period record (period type Month). ADvendio sends one request per fiscal period, with start and end set to the start and end dates of that period. Use start and end to select the data, and return the periodId unchanged in every response unit. When the org does not use custom fiscal periods, periodId is null and start and end define the reporting window.

Custom metrics. Return the customMetrics of the request in customMetricValues, exactly as requested, with the retrieved value in metricValue.

Timeout: ADvendio waits at most 60 minutes for the response.

Authorizations:
ApiKeyHeaderBearerAuth
Request Body schema: application/json
required
required
object (Connection)

Connection details for the target external system. Contains authentication credentials, endpoints, and connection configuration required to communicate with ad servers or other integrated systems.

orgId
required
string

Salesforce organization ID of the request context. Used to scope operations to the appropriate organizational unit and ensure proper data isolation and access control.

object or null

Custom request settings as key-value pairs. Allows for flexible configuration and extension of request properties without modifying the core request structure. Can include feature flags, processing options, or integration-specific parameters.

reportInterval
string (ReportInterval)
Enum: "TOTAL" "MONTHLY" "DAILY"

The interval for report aggregation. Determines the time grouping and aggregation level for the report data.

reportType
string (ReportType)
Enum: "SELLING" "BUYING"

The type of report to generate. Determines whether the report is for selling or buying operations.

adIds
Array of strings or null

List of advertisement IDs to include in the report. If not specified, the report may include all accessible advertisements based on the connection and organization context.

start
string or null <date-time>

Start date and time for the report period. Data will be included from this timestamp onwards.

end
string or null <date-time>

End date and time for the report period. Data will be included up to this timestamp.

periodId
string or null

Identifier of the custom fiscal period that this request covers: the Salesforce ID of the fiscal period record (period type Month) defined in the Salesforce org. It is only set when the org uses custom fiscal periods; ADvendio then sends one request per fiscal period, and start and end are set to the start and end dates of that period. Use start and end to select the data to return, and return the periodId unchanged in the response so that the metrics can be matched to their fiscal period. It is null when the org does not use custom fiscal periods.

Array of objects or null (ReportCustomMetric)

List of custom metrics to include in the report. These metrics will be calculated and included alongside standard metrics.

Responses

Response Schema: application/json
status
required
string
Enum: "SUCCESS" "ERROR"

Overall status of the operation. "SUCCESS" or "ERROR"

message
string or null

Descriptive message about the operation result. Provides additional context about the status, error details, or success information.

successCount
integer or null <int32>

Number of successfully processed operations. Used in bulk operations to indicate how many items were processed successfully.

failureCount
integer or null <int32>

Number of failed operations. Used in bulk operations to indicate how many items failed processing.

object or null

Custom response settings as key-value pairs. Allows for flexible extension of response properties without modifying the core response structure. Can include processing metadata, debug information, or integration-specific data.

currentPage
integer or null <int32>

Current page number for paginated responses. Can be 0-based or 1-based depending on the implementation.

pageSize
integer or null <int32>

Number of items per page in paginated responses. Indicates the page size used for this response.

totalElements
integer or null <int64>

Total number of items across all pages. Provides the complete count of items available, not just those in the current page.

totalPages
integer or null <int32>

Total number of pages available. Calculated based on totalElements and pageSize.

hasNext
boolean or null

Indicates whether there is a next page available. Useful for navigation in paginated results.

hasPrevious
boolean or null

Indicates whether there is a previous page available. Useful for navigation in paginated results.

isFirst
boolean or null

Indicates whether this is the first page. Useful for UI rendering and navigation logic.

isLast
boolean or null

Indicates whether this is the last page. Useful for UI rendering and navigation logic.

Array of objects or null (ReportResponseUnit)

Performance metrics for each advertisement in the reporting period: standard metrics (impressions, clicks, views, revenue, costs), calculated metrics (CTR, CPM, CPC, viewability rates), video and audio metrics, conversions and the custom metric values of the request. The granularity depends on the report interval: TOTAL (one unit per advertisement with aggregated metrics), MONTHLY (one unit per advertisement per month) and DAILY (one unit per advertisement per day). Each unit can report data collection issues in errors and warnings.

Request samples

Content type
application/json
Example
{
  • "connection": {
    • "salesforceId": "a0X5g000001234ABC",
    • "id": "ext-adserver-001",
    • "name": "Production Ad Server Connection",
    • "connectionType": "CustomMediaIntegration",
    • "username": "api_user@company.com",
    • "password": "SecurePassword123!",
    • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
    • "endpoint": "https://api.adserver.com/v1"
    },
  • "orgId": "00D5g000001AbCdEFG",
  • "reportInterval": "DAILY",
  • "reportType": "SELLING",
  • "adIds": [
    • "ad-homepage-banner-001",
    • "ad-video-preroll-001",
    • "ad-mobile-rectangle-001"
    ],
  • "start": "2025-10-01T00:00:00-04:00",
  • "end": "2025-10-31T23:59:59-04:00",
  • "periodId": "0265g000000AbCdEFG",
  • "customMetrics": [
    • {
      },
    • {
      }
    ]
}

Response samples

Content type
application/json
Example
{
  • "status": "SUCCESS",
  • "message": "Successfully generated daily selling report for fiscal period 0265g000000AbCdEFG",
  • "successCount": 2,
  • "failureCount": 0,
  • "currentPage": 0,
  • "pageSize": 100,
  • "totalElements": 2,
  • "totalPages": 1,
  • "hasNext": false,
  • "hasPrevious": false,
  • "isFirst": true,
  • "isLast": true,
  • "reportResponses": [
    • {
      },
    • {
      }
    ]
}

Status Sync

Status synchronization of advertisements in both directions.

Pull or push advertisement status

Synchronizes the status of advertisements between ADvendio and your system.

  • PULL: retrieve the current status of the advertisements in statusRequest.adIds from your system.
  • PUSH: set the status of the advertisements in statusRequest.adIdStatusMap in your system.

Return one StatusSyncResponseUnit per advertisement: the current status for PULL, the updated (or attempted) status for PUSH. Common status values are ACTIVE, PAUSED and INACTIVE.

Timeout: ADvendio waits at most 5 minutes for the response.

Authorizations:
ApiKeyHeaderBearerAuth
Request Body schema: application/json
required
required
object (Connection)

Connection details for the target external system. Contains authentication credentials, endpoints, and connection configuration required to communicate with ad servers or other integrated systems.

orgId
required
string

Salesforce organization ID of the request context. Used to scope operations to the appropriate organizational unit and ensure proper data isolation and access control.

operation
required
string

The type of status synchronization operation to perform. Determines whether this is a PULL (retrieve) or PUSH (update) operation.

required
object (StatusPullRequest)

The pull request payload.

object or null

Custom request settings as key-value pairs. Allows for flexible configuration and extension of request properties without modifying the core request structure. Can include feature flags, processing options, or integration-specific parameters.

Responses

Response Schema: application/json
status
required
string
Enum: "SUCCESS" "ERROR"

Overall status of the operation. "SUCCESS" or "ERROR"

message
string or null

Descriptive message about the operation result. Provides additional context about the status, error details, or success information.

successCount
integer or null <int32>

Number of successfully processed operations. Used in bulk operations to indicate how many items were processed successfully.

failureCount
integer or null <int32>

Number of failed operations. Used in bulk operations to indicate how many items failed processing.

object or null

Custom response settings as key-value pairs. Allows for flexible extension of response properties without modifying the core response structure. Can include processing metadata, debug information, or integration-specific data.

currentPage
integer or null <int32>

Current page number for paginated responses. Can be 0-based or 1-based depending on the implementation.

pageSize
integer or null <int32>

Number of items per page in paginated responses. Indicates the page size used for this response.

totalElements
integer or null <int64>

Total number of items across all pages. Provides the complete count of items available, not just those in the current page.

totalPages
integer or null <int32>

Total number of pages available. Calculated based on totalElements and pageSize.

hasNext
boolean or null

Indicates whether there is a next page available. Useful for navigation in paginated results.

hasPrevious
boolean or null

Indicates whether there is a previous page available. Useful for navigation in paginated results.

isFirst
boolean or null

Indicates whether this is the first page. Useful for UI rendering and navigation logic.

isLast
boolean or null

Indicates whether this is the last page. Useful for UI rendering and navigation logic.

Array of objects or null (StatusSyncResponseUnit)

List of status synchronization response units. Each unit in this list represents the status information for a specific advertisement. For PULL operations, this contains the current status retrieved from external systems. For PUSH operations, this contains confirmation of status updates or error information.

Request samples

Content type
application/json
Example
{
  • "connection": {
    • "salesforceId": "a0X5g000001234ABC",
    • "id": "ext-adserver-001",
    • "name": "Production Ad Server Connection",
    • "connectionType": "CustomMediaIntegration",
    • "username": "api_user@company.com",
    • "password": "SecurePassword123!",
    • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
    • "endpoint": "https://api.adserver.com/v1"
    },
  • "orgId": "00D5g000001AbCdEFG",
  • "operation": "PULL",
  • "statusRequest": {
    • "adIds": [
      ]
    }
}

Response samples

Content type
application/json
Example
{
  • "status": "SUCCESS",
  • "message": "Retrieved the status of 5 advertisements",
  • "successCount": 5,
  • "failureCount": 0,
  • "currentPage": 0,
  • "pageSize": 100,
  • "totalElements": 5,
  • "totalPages": 1,
  • "hasNext": false,
  • "hasPrevious": false,
  • "isFirst": true,
  • "isLast": true,
  • "statusSyncResponses": [
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ]
}

Wallet

Two complementary operations that synchronize budget and spending information between Salesforce and your ad server.

Push wallets to the ad server

Synchronizes wallet (budget) data from Salesforce to your ad server. The wallets are grouped by ad server account ID in walletsByAccount.

Return one WalletResponseUnit per wallet, with the wallet data as saved in your ad server, including the fields generated by your server. In a successful unit, wallet.id and wallet.account are required.

isManaged: ADvendio always sends true or false. Return it only if your ad server reports it; if it is null or missing, ADvendio keeps the value stored on the wallet.

Timeout: ADvendio waits at most 30 minutes for the response.

Authorizations:
ApiKeyHeaderBearerAuth
Request Body schema: application/json
required
required
object (Connection)

Connection details for the target external system. Contains authentication credentials, endpoints, and connection configuration required to communicate with ad servers or other integrated systems.

orgId
required
string

Salesforce organization ID of the request context. Used to scope operations to the appropriate organizational unit and ensure proper data isolation and access control.

required
object

Wallets by ad server account ID.

object or null

Custom request settings as key-value pairs. Allows for flexible configuration and extension of request properties without modifying the core request structure. Can include feature flags, processing options, or integration-specific parameters.

Responses

Response Schema: application/json
status
required
string
Enum: "SUCCESS" "ERROR"

Overall status of the operation. "SUCCESS" or "ERROR"

message
string or null

Descriptive message about the operation result. Provides additional context about the status, error details, or success information.

successCount
integer or null <int32>

Number of successfully processed operations. Used in bulk operations to indicate how many items were processed successfully.

failureCount
integer or null <int32>

Number of failed operations. Used in bulk operations to indicate how many items failed processing.

object or null

Custom response settings as key-value pairs. Allows for flexible extension of response properties without modifying the core response structure. Can include processing metadata, debug information, or integration-specific data.

Array of objects or null (WalletResponseUnit)

Individual results for each wallet.

Request samples

Content type
application/json
{
  • "connection": {
    • "salesforceId": "a0Q5g000001XYZ1EAO",
    • "id": "conn_12345",
    • "name": "Ad Server Connection",
    • "connectionType": "CustomMediaIntegration",
    • "username": "api_user@example.com",
    • "endpoint": "https://adserver.example.com/api/v1",
    • "customEntitySettings": {
      }
    },
  • "orgId": "00D5g000001AbcdEAC",
  • "walletsByAccount": {
    • "account_789": [
      ]
    }
}

Response samples

Content type
application/json
{
  • "status": "ERROR",
  • "message": "Wallet operation completed with 1 success and 1 failure",
  • "successCount": 1,
  • "failureCount": 1,
  • "walletResponses": [
    • {
      },
    • {
      }
    ]
}

Pull wallets and campaign associations

Retrieves wallet (budget) data and the associations between wallets and campaigns from your ad server to Salesforce.

If the wallet list of an account in walletsByAccount is empty, return all wallets of that account or connection. Return the wallet-campaign associations of the campaigns in campaignIds in campaignAssociations.

Timeout: ADvendio waits at most 30 minutes for the response.

Authorizations:
ApiKeyHeaderBearerAuth
Request Body schema: application/json
required
required
object (Connection)

Connection details for the target external system. Contains authentication credentials, endpoints, and connection configuration required to communicate with ad servers or other integrated systems.

orgId
required
string

Salesforce organization ID of the request context. Used to scope operations to the appropriate organizational unit and ensure proper data isolation and access control.

required
object

Wallets by ad server account ID. If the list of an account is empty, return all wallets associated with that account or connection.

object or null

Custom request settings as key-value pairs. Allows for flexible configuration and extension of request properties without modifying the core request structure. Can include feature flags, processing options, or integration-specific parameters.

campaignIds
Array of strings or null

List of campaign IDs to query. Used to retrieve wallet-campaign associations.

Responses

Response Schema: application/json
status
required
string
Enum: "SUCCESS" "ERROR"

Overall status of the operation. "SUCCESS" or "ERROR"

message
string or null

Descriptive message about the operation result. Provides additional context about the status, error details, or success information.

successCount
integer or null <int32>

Number of successfully processed operations. Used in bulk operations to indicate how many items were processed successfully.

failureCount
integer or null <int32>

Number of failed operations. Used in bulk operations to indicate how many items failed processing.

object or null

Custom response settings as key-value pairs. Allows for flexible extension of response properties without modifying the core response structure. Can include processing metadata, debug information, or integration-specific data.

Array of objects or null (WalletResponseUnit)

Individual results for each wallet.

Array of objects or null (WalletCampaignAssociation)

Contains mappings between wallets and campaigns, showing which wallets are assigned to which campaigns.

Request samples

Content type
application/json
{
  • "connection": {
    • "salesforceId": "a0Q5g000001XYZ1EAO",
    • "id": "conn_12345",
    • "name": "Ad Server Connection",
    • "endpoint": "https://adserver.example.com/api/v1",
    • "connectionType": "CustomMediaIntegration"
    },
  • "orgId": "00D5g000001AbcdEAC",
  • "customRequestSettings": {
    • "includeSpending": "true",
    • "includeCampaignAssociations": "true"
    },
  • "walletsByAccount": {
    • "account_789": [
      ]
    },
  • "campaignIds": [
    • "campaign_555",
    • "campaign_666",
    • "campaign_777"
    ]
}

Response samples

Content type
application/json
{
  • "status": "SUCCESS",
  • "message": "Wallet pull completed successfully",
  • "successCount": 2,
  • "failureCount": 0,
  • "walletResponses": [
    • {
      },
    • {
      }
    ],
  • "campaignAssociations": [
    • {
      },
    • {
      },
    • {
      }
    ]
}

Campaign Import

Import campaigns and line items from your ad server into Salesforce.

Import campaigns from the ad server

Imports campaign and line item data from your ad server into Salesforce: budget, status, schedule and all associated line items. Filter the campaigns with dateFrom, dateTo, campaignStatus and adServerAccountId.

The response is a stream with the media type application/stream+json: one SellingImportResponseUnit per line, each with one complete campaign and its items.

Import by account

From version 2.186, when accounts with an external ID are assigned to the Connection in ADvendio (Accounts by AdServer), ADvendio sends one Campaign Import request for each account, with adServerAccountId set to the ID of that account. Filter the campaigns by this ID and return only the campaigns of that account. A service that ignores adServerAccountId receives one identical, unfiltered request for each account and returns all campaigns each time.

  • The accounts are processed one after another, sorted by ID, with a pause of 200 to 500 milliseconds between two requests.
  • If the request of one account fails, ADvendio still sends the requests of the other accounts. The error messages of an account start with Account {id}:.
  • The import of a Connection fails only when the requests of all its accounts fail.
  • When no account is assigned to the Connection, or when the Connection has the ad server feature "Disable Campaign Import By Account" active, ADvendio sends a single request with adServerAccountId set to null. Return all campaigns in this case.

How ADvendio reads the dates

ADvendio saves the start and end of campaigns and items as calendar dates, without a time. Your service can return the dates in two ways:

  • Calendar days (default). Return the calendar day of the ad account, for example 2024-06-01T00:00:00Z. ADvendio saves the date part as it is sent (2024-06-01), whatever the offset is.
  • Points in time. Return real instants and add the key dateSemantics with the value INSTANT (the value is not case-sensitive) to the customEntitySettings of the campaign. ADvendio then converts the start and end of the campaign and of all its items to the Network Time Zone of the Connection and saves the calendar day in that time zone. For example, 2024-05-31T22:00:00Z is saved as 2024-06-01 when the Network Time Zone is Europe/Berlin.

If the Connection has no valid Network Time Zone, ADvendio saves the date part as it is sent, with or without dateSemantics. Do not convert the dates yourself when you use INSTANT.

Example stream

A complete response with two campaigns (one JSON object per line):

{"errors":[],"warnings":["Budget exceeds typical campaign range"],"campaignData":{"salesforceId":null,"id":"campaign_12345","name":"Summer Campaign 2024","startDate":"2024-06-01T00:00:00Z","endDate":"2024-08-31T23:59:59Z","advertiserId":"advertiser_001","agencyId":"agency_001","status":"ACTIVE","budget":50000,"currency":"EUR","description":"Summer promotional campaign for new product launch","customEntitySettings":{"campaignType":"DISPLAY","priority":"HIGH"},"errors":[],"warnings":[],"items":[{"salesforceId":null,"id":"item_67890","name":"Banner Ad - Desktop","startDate":"2024-06-01T00:00:00Z","endDate":"2024-08-31T23:59:59Z","quantity":1000000,"salesPrice":1.2,"billingCategory":"CPM","status":"ACTIVE","targetingPayload":"{\"geo\":[\"US\",\"CA\"],\"age\":[\"18-34\",\"35-54\"],\"device\":[\"desktop\"]}","customEntitySettings":{"adSize":"728x90","placement":"ATF"},"errors":[],"warnings":[]},{"salesforceId":null,"id":"item_67891","name":"Banner Ad - Mobile","startDate":"2024-06-15T00:00:00Z","endDate":"2024-08-31T23:59:59Z","quantity":500000,"salesPrice":0.5,"billingCategory":"CPC","status":"ACTIVE","targetingPayload":"{\"geo\":[\"US\"],\"age\":[\"18-34\"],\"device\":[\"mobile\",\"tablet\"]}","customEntitySettings":{"adSize":"320x50","placement":"BTF"},"errors":[],"warnings":["Low inventory available for mobile placement"]}]}}
{"errors":[],"warnings":[],"campaignData":{"salesforceId":null,"id":"campaign_12346","name":"Fall Campaign 2024","startDate":"2024-09-01T00:00:00Z","endDate":"2024-11-30T23:59:59Z","advertiserId":"advertiser_002","agencyId":"agency_002","status":"PENDING","budget":75000,"currency":"EUR","description":"Fall seasonal campaign targeting back-to-school audience","customEntitySettings":{"campaignType":"VIDEO","priority":"MEDIUM"},"errors":[],"warnings":[],"items":[{"salesforceId":null,"id":"item_67892","name":"Pre-roll Video Ad","startDate":"2024-09-01T00:00:00Z","endDate":"2024-11-30T23:59:59Z","quantity":250000,"salesPrice":1.5,"status":"PENDING","targetingPayload":"{\"geo\":[\"US\",\"CA\",\"UK\"],\"age\":[\"18-24\",\"25-34\"],\"interests\":[\"education\",\"technology\"]}","customEntitySettings":{"videoDuration":"15s","format":"MP4"},"errors":[],"warnings":[]}]}}

Timeout: ADvendio waits at most 30 minutes for the response.

Authorizations:
ApiKeyHeaderBearerAuth
Request Body schema: application/json
required
required
object (Connection)

Connection details for the target external system. Contains authentication credentials, endpoints, and connection configuration required to communicate with ad servers or other integrated systems.

orgId
required
string

Salesforce organization ID of the request context. Used to scope operations to the appropriate organizational unit and ensure proper data isolation and access control.

object or null

Custom request settings as key-value pairs. Allows for flexible configuration and extension of request properties without modifying the core request structure. Can include feature flags, processing options, or integration-specific parameters.

dateFrom
string or null <date>

Start date for the campaign date range filter. When specified, only campaigns with a start date on or after this date will be imported. This field works in conjunction with dateTo to define the date range filter.

dateTo
string or null <date>

End date for the campaign date range filter. When specified, only campaigns with a start date on or before this date will be imported. This field works in conjunction with dateFrom to define the date range filter.

campaignStatus
string or null
Default: "All"
Examples: "All" "Active" "PENDING,PAUSED"

Campaign status filter for selective import. Supported values: "All" (import campaigns with all statuses - no filtering), "Active" (import only active campaigns), any specific status value (e.g., "PENDING", "PAUSED", "COMPLETED") or a comma-separated list of status values (e.g., "PENDING,PAUSED,COMPLETED"). Default: "All"

adServerAccountId
string or null

Optional filter: the ID of an account in the ad server, for example a vendor. When set, return only the campaigns that belong to this account. When null, return the campaigns of all accounts. From version 2.186, ADvendio sends one request for each account that is assigned to the Connection (see Import by account).

debug
boolean or null
Default: false

Debug mode flag for detailed logging and diagnostics. When set to true, enables verbose logging and includes additional diagnostic information in the response. This is useful for troubleshooting import issues during development and testing. Default: false

Responses

Response Schema: application/stream+json
salesforceId
string or null

The Salesforce ID for this entity. Used to link entities back to their corresponding Salesforce records.

id
string or null

The ad server ID for this entity. This is the primary identifier used by the external ad server system.

name
string or null

The ad server name for this entity. Human-readable name used by the external ad server system.

object or null

Custom entity settings as key-value pairs. Allows for flexible configuration and extension of entity properties without modifying the core data structure. The values are always strings. See Custom Fields.

errors
Array of strings or null

List of error messages associated with this entity. Used to report validation errors, processing errors, or system errors encountered during entity operations.

warnings
Array of strings or null

List of warning messages associated with this entity. Used to report non-fatal issues or important notifications that don't prevent processing but should be noted.

object (CampaignData)

Complete campaign data imported from the external ad server. Contains all campaign-level information including schedule, budget, status, and a collection of associated line items.

Request samples

Content type
application/json
{
  • "connection": {
    • "salesforceId": "a0X5g000001234ABC",
    • "id": "ext-adserver-001",
    • "name": "Production Ad Server Connection",
    • "connectionType": "CustomMediaIntegration",
    • "username": "api_user@company.com",
    • "password": "SecurePassword123!",
    • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
    • "endpoint": "https://api.adserver.com/v1"
    },
  • "orgId": "00D5g000001AbCdEFG",
  • "dateFrom": "2024-06-01",
  • "dateTo": "2024-12-31",
  • "campaignStatus": "Active",
  • "debug": false,
  • "customRequestSettings": {
    • "includeArchivedItems": "false",
    • "batchSize": "100"
    },
  • "adServerAccountId": "account_789"
}

Response samples

Content type
application/stream+json
{
  • "errors": [ ],
  • "warnings": [
    • "Budget exceeds typical campaign range"
    ],
  • "campaignData": {
    • "salesforceId": null,
    • "id": "campaign_12345",
    • "name": "Summer Campaign 2024",
    • "startDate": "2024-06-01T00:00:00Z",
    • "endDate": "2024-08-31T23:59:59Z",
    • "advertiserId": "advertiser_001",
    • "agencyId": "agency_001",
    • "status": "ACTIVE",
    • "budget": 50000,
    • "currency": "EUR",
    • "description": "Summer promotional campaign for new product launch",
    • "customEntitySettings": {
      },
    • "errors": [ ],
    • "warnings": [ ],
    • "items": [
      ]
    }
}

Targeting

The TargetingCriteria entity defines the targeting of Selling and Buying Items (targetingCriteria). It is also sent with the items of a Forecast request.

Structure

TargetingCriteria holds a list of targets and the flag isEmpty. Each Target is a node of a tree:

Field Type Description
adServerEntities List of AdServerEntity The ad server entities that are targeted: audience segments, inventory, geography and so on.
targets List of Target Nested targets, for logical combinations.
logicOperator String && (and), || (or) and ! (not) for groups. ==, !=, <, >, <=, >=, IN or EX for comparisons.
type String Type of the node: LIST for a group of targets, ID for an ad server entity, STRING or TEXT for a value.

How targeting is defined in ADvendio

Targeting for a CMI connection is defined in the same way as for other ad servers: with targeting sets and with the targeting of each Campaign Item. The values come from the Connection IDs imported from your ad server (see Ad Server Entities). When a Campaign Item uses several targeting sets, sets in the same targeting group are combined with OR, different groups are combined with AND, and the result is combined with AND with the Campaign Item's own targeting.

Every target is an ad server entity (AdServerEntity) that ADvendio holds for the Connection, normally imported through Ad Server Entity Retrieval. Targeting that is not defined in the ad server cannot be sent in targetingCriteria.

How targeting is sent

The targetingCriteria of each SellingItem holds one target per targeting category: AUDIENCE_SEGMENT, GEOGRAPHY, INVENTORY, DEVICE, BRAND, CONNECTION, INDUSTRY, KEY_VALUE, MOBILE_APPLICATION, POSTAL_CODE, VIDEO_CONTENT, VIDEO_POSITION and ACCOUNT.

Each target is a tree: groups combine their child targets with logicOperator, and each leaf holds the ad server entity as you returned it in the entity import (id, name, type, category and parent). The customEntitySettings of each entity carry:

  • EXTRA_FIELD.exclude|NO_ID: "true" for an excluded entity,
  • EXTRA_FIELD.adServerName|NO_ID,
  • EXTRA_FIELD.parentId|NO_ID,
  • EXTRA_FIELD.foreignId|NO_ID.

When nothing is targeted, isEmpty is true.

Some targeting is sent in separate SellingItem fields instead:

  • dayTimeTargeting: the day and time targeting as a JSON string.
  • frequencyCapping: one text per rule, for example "10 per 2 hours".
  • userDomainsIncluded and userDomainsExcluded.
  • masterSlotSize and companionSlotSize.
  • supplyStrategies.

Forecast requests carry the same targeting as booking requests.

BuyingItems carry their own targetingCriteria, with the buying categories GEOGRAPHY, POSTAL_CODE, BROWSER, DEVICE, DEVICE_TYPE, DEVICE_MAKE_MODEL, LANGUAGE, EXCHANGE, SUB_EXCHANGE, INVENTORY, INVENTORY_SOURCE, INVENTORY_SOURCE_GROUP, AUDIENCE_SEGMENT and BRAND_SAFETY. Only the targeting of the item itself is sent, not the targeting of the order. Frequency capping and the target platform are sent in the frequencyCapping and targetPlatform fields of the BuyingItem.

In a Campaign Import, the targetingPayload you return is stored as is on the Campaign Item and is not converted into Connection IDs.

Your integration is expected to map each entity id to the matching object in your ad server, apply the logic operators and exclusions, and return a warning for any targeting it cannot apply.

Example

Germany is targeted, Berlin is excluded, and the item is limited to desktop devices. The exact tree that ADvendio builds depends on the targeting sets and on the targeting of the Campaign Item.

{
  "isEmpty": false,
  "targets": [
    {
      "type": "LIST",
      "logicOperator": "&&",
      "targets": [
        {
          "type": "ID",
          "logicOperator": "==",
          "adServerEntities": [
            {
              "id": "76309",
              "name": "Germany",
              "type": "Country",
              "category": "Geography",
              "customEntitySettings": { "EXTRA_FIELD.exclude|NO_ID": "false" }
            }
          ]
        },
        {
          "type": "ID",
          "logicOperator": "!=",
          "adServerEntities": [
            {
              "id": "6923483",
              "name": "Berlin",
              "type": "City",
              "category": "Geography",
              "customEntitySettings": {
                "EXTRA_FIELD.exclude|NO_ID": "true",
                "EXTRA_FIELD.parentId|NO_ID": "76309"
              }
            }
          ]
        }
      ]
    },
    {
      "type": "LIST",
      "logicOperator": "||",
      "targets": [
        {
          "type": "ID",
          "logicOperator": "==",
          "adServerEntities": [
            {
              "id": "30000",
              "name": "Desktop",
              "type": "Device Category",
              "category": "Devices",
              "customEntitySettings": { "EXTRA_FIELD.exclude|NO_ID": "false" }
            }
          ]
        }
      ]
    }
  ]
}

Schema

Array of objects or null (Target)

List of all targeting conditions to be applied. Each Target in this list represents a specific targeting rule that will be evaluated and applied to the campaign or line item.

isEmpty
boolean or null

Indicates whether the targeting criteria is empty. When true, no specific targeting is applied, which may result in broad targeting depending on the system's default behavior.

{
  • "targets": [
    • {
      }
    ],
  • "isEmpty": true
}

Custom Fields

The customEntitySettings attribute transmits additional metadata and custom fields that are not part of the standard CMI interface. It is available for the Selling and Forecast operations and, from version 2.186, for the Connection IDs of the Ad Server Entity Retrieval (see Connection ID custom fields). As an integration partner, you receive requests that contain this data, and you should include it in your responses to keep the data consistent.

What you receive. In CMI requests, customEntitySettings contains:

  • Extended data: additional fields that don't fit into the standard CMI data model.
  • Platform-specific metadata: custom settings and configurations.
  • Custom fields: user-defined fields from Salesforce (Selling and Forecast operations only). A custom field is sent only if it has a value in ADvendio.

What you return. In your responses:

  • Preserve custom fields: return the same custom fields you received.
  • Keep the format: use the same key format.

Key format rules

Standard extra fields

For predefined system fields, the key format is:

EXTRA_FIELD.{fieldName}|NO_ID
  • Prefix EXTRA_FIELD.: identifies the field as an extra field.
  • {fieldName}: the field identifier.
  • Separator |: separates the field name from the ID.
  • Suffix NO_ID: no specific object ID is associated with the field.

Examples you'll receive:

EXTRA_FIELD.adServerName|NO_ID
EXTRA_FIELD.parentId|NO_ID
EXTRA_FIELD.foreignId|NO_ID
EXTRA_FIELD.exclude|NO_ID
EXTRA_FIELD.forecastSlotSize|NO_ID
EXTRA_FIELD.oneImpPerPage|NO_ID
EXTRA_FIELD.orderCampaignId|NO_ID
EXTRA_FIELD.creativeManagement|NO_ID

Custom fields

Custom fields are available for SellingOrder and SellingItem, including the items of a forecast request. The key format is:

{dataFieldPath}|{dataObjectId}
  • {dataFieldPath}: the field path in Salesforce.
  • Separator |: separates the path from the object ID.
  • {dataObjectId}: the Salesforce record ID.
  • From version 2.186, when the custom field mapping in ADvendio has an ID string (the ID of the field in your ad server), a third part is added: {dataFieldPath}|{dataObjectId}|{idString}. Return the key exactly as you received it.

Examples you'll receive:

ADvendio__MediaCampaign__c.CustomBudget__c|a1EDp000005K59hMAC
ADvendio__Campaign_Item__c.AnotherField__c|a1EDp000008Kh10MRH
ADvendio__Campaign_Item__c.SpecialFlag__c|a1EDp000008Kh10MRH|1234567

In a Forecast request, each item carries its custom fields in the same format. The forecast request has no order level, so the campaign (order) custom fields are sent on each item together with the item custom fields. Items of a campaign that has not been saved in Salesforce yet are sent without custom fields.

Handling requests

When you receive a request with customEntitySettings:

  1. Parse the keys: split the keys by the pipe character to identify the field types.
  2. Extract standard fields: look for the EXTRA_FIELD. prefix for system fields.
  3. Extract custom fields: handle keys in the {path}|{id} format for user-defined fields.
  4. Store them for the response: keep track of the custom fields to return in the response.
  5. Use them for processing: apply any relevant custom settings to your operations.

Received customEntitySettings:

"customEntitySettings": {
  "EXTRA_FIELD.adServerName|NO_ID": "XANDR",
  "EXTRA_FIELD.parentId|NO_ID": "parent123",
  "ADvendio__MediaCampaign__c.CustomBudget__c|a239K00000HKw1HQAT": "50000",
  "ADvendio__Campaign_Item__c.SpecialFlag__c|a0y9K0000032XHMQA2": "true"
}

Your processing:

  • Extract adServerName = "XANDR" for platform identification.
  • Extract parentId = "parent123" for hierarchy management.
  • Extract the custom budget "50000" for campaign processing. Numeric values longer than 7 digits can be sent in scientific notation.
  • Extract the special flag "true" for item-specific logic.

Building responses

Fields received as EXTRA_FIELD are not required in the response.

  • Preserve received fields: return all custom fields you received. Return the values as text.
  • Keep the format: use the same keys.

Your response customEntitySettings:

"customEntitySettings": {
  "ADvendio__MediaCampaign__c.CustomBudget__c|a239K00000HKw1HQAT": "60000",
  "ADvendio__Campaign_Item__c.SpecialFlag__c|a0y9K0000032XHMQA2": "false"
}

Connection ID custom fields

From version 2.186, the Ad Server Entity Retrieval can also request custom fields for the Connection IDs that it imports. ADvendio sends them only when custom fields are configured for Connection IDs in ADvendio.

What you'll receive

The customRequestSettings of the request contain one entry for each configured field. The key has three parts, and the value is the name of the configuration record:

{dataFieldPath}|{dataObjectId}|{idString}
  • {dataFieldPath}: always ADvendio__AdServer_ID__c.{Field API name}.
  • {dataObjectId}: always the placeholder AAA000BBB000CCCMAI. The import request is not tied to one Connection ID record, so there is no Salesforce ID to send.
  • {idString}: the ID of the field in your ad server, as set in the custom field mapping. It is left out when no ID string is configured.
"customRequestSettings": {
  "ADvendio__AdServer_ID__c.Network_Code__c|AAA000BBB000CCCMAI|networkCode": "Network Code",
  "ADvendio__AdServer_ID__c.Tier__c|AAA000BBB000CCCMAI|tier": "Tier"
}

What you should return

For each AdServerEntity that you return, add the requested keys to its customEntitySettings, exactly as received, with the value that you read from the ad server for that entity. Keys that were not requested are ignored. Do not change a key, including the placeholder and the case of the field path.

{
  "id": "12345",
  "name": "Advertiser A",
  "type": "Advertiser",
  "category": "Accounts",
  "customEntitySettings": {
    "ADvendio__AdServer_ID__c.Network_Code__c|AAA000BBB000CCCMAI|networkCode": "NET-42",
    "ADvendio__AdServer_ID__c.Tier__c|AAA000BBB000CCCMAI|tier": "Gold"
  }
}

How ADvendio saves the values

ADvendio writes the values to the Connection ID record, new or existing, in the same import. An empty or missing value leaves the Salesforce field unchanged. The value must match the type of the Salesforce field:

  • text within the field length,
  • numbers within precision and scale (extra decimals are rounded),
  • true or false for checkboxes,
  • yyyy-MM-dd for dates,
  • ISO 8601 with offset for date-times, for example 2026-10-15T10:30:00Z,
  • an allowed value for restricted picklists.

An invalid value is skipped with a warning in the job, and the Connection ID is still imported. Custom fields of parent entities are not read: each Connection ID gets its values when it is imported as an entity itself.

Log Viewer

The Log Viewer records every call between your ADvendio jobs and your custom media integration.

What gets logged

For each external API call, the Log Viewer captures:

  • The request: what ADvendio sent to your service.
  • The response: what your service sent back.
  • The endpoint: which URL was called.

Security first

  • Sensitive data is removed automatically. Passwords, API keys and tokens are replaced with ***REDACTED***. This applies to the values of the fields token, password, secret, pin, bearer, authorization, apiKey, accessToken, refreshToken, clientSecret and privateKey (also written api_key, api-key, client-secret and so on), whatever the letter case. A number or a boolean in one of these fields is replaced with null. Other fields are not masked, so do not return secrets in other fields.
  • Only authorized users can view logs. Access is controlled through your existing Salesforce permissions.
  • No confidential information is stored.

How to access your logs

  1. Run your job: run any of the supported job types through your usual process.
  2. Check your email: when the job completes, you receive an email with the results. It contains a job information table with a direct link to the detailed logs.
  3. Find the job link: the table shows the Org, the User who ran the job, the Connection(s) used and the Job, a clickable job ID.
  4. Click the job ID: for example, the email shows Job: 3374, which links to https://your-instance.salesforce.com/apex/ADvendio__MediaCloudJob?jobId=3374.
  5. Review the logs: the Log Viewer page shows all external API calls made during the job, the request and response details of each call, and any error messages from external platforms.

What the email looks like

Field Value
Org [Your Salesforce Org] (Production/Sandbox)
User [Your Username]
Connection(s) [Platform Connections Used]
Job [Clickable Job ID Number]
Start [Job Start Time]
End [Job End Time]

What you'll see in the logs

  • Endpoint URL: which API was called.
  • Type: Request or Response.
  • Request/Response body: the data sent and received.

Best Practices

Authentication and security

  • Always use secure HTTPS endpoints with TLS 1.2 or above.
  • Rotate the API key regularly.
  • Store credentials securely and never expose them in logs.
  • ADvendio sends the API key in the request headers X-API-Key and Authorization (as a Bearer token), and in the request body as connection.token. Do not send the API key back in a response header.

Error handling

  • Use successCount and failureCount for bulk operations.
  • Implement retry logic for transient failures in the calls to your ad server. ADvendio does not retry a failed call. It waits at most 5 minutes for login, booking, buying, forecast and status sync, 30 minutes for entity import, campaign import and wallet, and 60 minutes for reports.

Performance

  • Return the complete result in one response: ADvendio does not request further pages, and the paging fields are informational.
  • Batch operations when possible to reduce API calls.
  • Cache frequently accessed data, like ad server entities.
  • Use appropriate report intervals to balance detail with performance.

Data validation

  • Validate date ranges before you submit requests to your ad server.
  • Make sure that budget amounts and impressions are positive values.
  • Verify that the targeting criteria are complete.
  • Check the required fields for each operation.

FAQ

The questions that integration partners ask most often.

How does ADvendio authenticate to my endpoints?

Every request is sent over HTTPS and carries the API key generated on the Connection (see Set up your API key). The key is sent in the X-API-Key header and in the Authorization: Bearer header, and also in the connection.token field of the request body. If you need OAuth, validate the key in your endpoint or an API gateway in front of it, and handle OAuth for your own systems there.

Which IP addresses does ADvendio use to call my endpoints?

The requests are sent by the ADvendio Gateway, not by your Salesforce org. To allowlist ADvendio in your network, contact ADvendio Support for the current IP ranges.

How do I set the technical name of an imported ad server entity?

The technical name (ADvendio__AdServer_Name__c) is not a standard field of the AdServerEntity (see Ad Server Entities). Send it in the customEntitySettings of the entity with the key EXTRA_FIELD.adServerName|NO_ID:

{
  "id": "12345",
  "name": "Homepage Top",
  "type": "Ad Unit",
  "category": "Inventory",
  "customEntitySettings": {
    "EXTRA_FIELD.adServerName|NO_ID": "site/homepage/top"
  }
}

Why does the Active checkbox of an imported ad server entity stay unchecked?

The status that your service returns for an entity is saved in the Status field of the Connection ID. The Active checkbox is not set from the response.

Which fields does my selling response need to contain?

For each Campaign Item, return salesforceId, id and orderId. salesforceId links the result to the Campaign Item, so return it for every item. id and orderId are the ad server IDs of the item and of its order, and ADvendio saves them. advertiserId, itemNew, orderNew, advertiserNew, warnings, errors, infoMessages and customEntitySettings are optional. See the response of Selling for the description of each field.

Why is targeting missing from the request?

ADvendio sends the targeting that is saved on the Campaign Item, together with the default targeting of its Ad Spec and Ad Type. Connection ID assignments are not sent as targeting. This applies to the IDs assigned to an Ad Spec or to content, and to the IDs selected on the Campaign Item. When no targeting is saved, targetingCriteria is empty and isEmpty is true. To send targeting, define it on the Campaign Item, for example in the Media Configurator or with targeting sets (see Targeting).

Are custom fields sent with forecast requests?

From version 2.186, yes. Each item of the forecast request carries its custom fields in customEntitySettings, in the same format as in a selling request (see Forecast and Custom Fields). Before version 2.186, custom fields are sent with selling requests only.

Who do I contact for support?

For additional support or questions about the Custom Media Integration Callback API (CMI), contact the ADvendio Connections Team.

Appendix

AdServerEntity categories

Values of category in the Ad Server Entity Retrieval request.
Inventory Key-Values Audience Segments Geography
Devices Connection Mobile application Order
CreativeTemplate Video Content Video Positions Industry
Brand Targeting Accounts Image Content
CMS-Key-values Yield Optimization Brand Safety Attribution

AdServerEntity types

Values of types in the Ad Server Entity Retrieval request.
Actalike Ad Creative Ad Image AdNetwork
Ad Unit Group Ad Unit Package Ad Unit Ad Video
Addressability Advertiser Agency Airport
Geo Target Platform Target App Category Attachment
Audience Item Audience Network Position Audience Segment Value (First Party) Audience Segment Value (Shared)
Audience Segment Value (Third Party) Audience Segment Value Audience Segment Autonomous Community
Balance Bandwidth Bandwidth Group Brand Company
Brand Browser Language Browser Buyer Seats
Canton Category CategoryExclusion Channel
City Subregion City CMA Region CMS Key
CMS Value Connection Type Congressional District ContentBundles
Content Category Content Credential Status Content Daypart Content Duration
Content Package Content Territory Content Unit Group Content Unit
Country County Creative CreativeCustomTemplate
CreativeStandardTemplate Criteria NotCriteria Custom Audiences
Customer List Deal Delivery Method Department
Device Capability Device Category Device Manufacturer Device Platform
Device Platforms Device Type Distribution Configuration DMA Region
DMA DSP Email Zone Endpoint Name
Endpoint Owner Engagement Environment Exchange
Facebook Position Fixed Price Contract FlexTreeValue Floodlight Activity
Format Genre Global Agency Governorate
Group IAB Industry Group Industry Sub-Group
Industry Instagram Position Integer Interest
Inventory Package Inventory Prioritization Configuration Inventory Type Inventory
Isp Key Label Landing Page
Language Market Messenger Position Mobile App Instance
Mobile App Store Mobile App Mobile Carrier Mobile Device Submodel
Mobile Device MSA Region MSA Municipality
Neighborhood Negative Keyword Lists Content Label Operating System Family
Operating System Version Operating System Optimization Event OS
Pack Page Group Page Promoted Pages
Pixel Placement Position Postal Code
Postal Code List Prefecture Privacy Product
Programmatic Buyer Programmatic Direct Deal Programmatic Guaranteed Contract Programmer
Province Publisher Platforms Publisher Zones Publisher
Radius Location Lists Region Regional Location Lists Retailer
Series Site Channel Site Id Site Directory Id
Site Group Site Section Site State
Station Stream Type String Sub Exchange
Subregion Subscription Model Supply Type Territory
Tv Rating Tv Region Tag Team
Text Zone Third Party Ad Tag Type FlexTreeKey Union Territory
URL User Agent Device Family User Account User Agent Device
User Agent Family User Agent OS User Agent Platform User Agent
User Device User Os Value VAST Channel
VAST Zone Venue Venue Group VideoContent
Video Group Video Position Video Visitor
Volume Cap Configuration Website Zone Group Zone Roll Type
Zone Zone Tag Sensitivity Category