UBX makes various application programming interfaces (API) available to integrate business applications with UBX.
IBM Commerce and IBM Business Partner solutions call UBX APIs to connect to UBX, to provide descriptive information that appears in the UBX user interface, and to manage the exchange of event and audience data between separate business applications.
IBM reserves the right to add optional properties to the current version of the UBX public APIs and it might add extra data to the response JSON. Any additional data will be in JSON format. If IBM adds, changes, or removes required properties in a UBX public API, it will create a new version of the API.
UBX API overview
IBM Commerce applications and authorized IBM Business Partners can call various REST APIs to establish and maintain a presence in UBX.
UBX provides the following types of APIs.
- Application-level APIs
- Endpoint-level APIs: Endpoint API: Custom Endpoints
- Event APIs: Event API
- Jobs APIs: Jobs API
- Identity management APIs: Identity management APIs
- Account-level APIs: Account-level API
Requests to UBX public APIs
Call UBX public APIs by submitting requests over SSL to the base URL that is provided by
the UBX provisioning team for your UBX account.
When IBM creates your UBX account, the UBX Provisioning team provides your organization with access credentials and base URL for API calls to the UBX Pilot environment. When your account moves to the Production environment, the Provisioning team updates the base URL to point to Production. Direct all calls to the UBX public APIs to the base URL that is assigned to your UBX account.
Calls to UBX public APIs must contain a valid authentication key that IBM provides to UBX users for each endpoint that they register. The authentication key must appear in the HTTP header of the API call. UBX rejects any API call that does not specify an authentication key that UBX can associate with a valid UBX account.
The authentication key identifies the UBX endpoint and a specific UBX user account that is associated with the endpoint.
All data exchanges through UBX occur on behalf of a specific UBX user and user account. Including an authentication key with each API call ensures that the data is directed to the correct destination and that customer identifiers are attributed to the correct UBX account. UBX does not share identifier data across UBX accounts.
To avoid SSL setup and teardown performance problems, your HTTP client must respect Keep-Alive headers returned by UBX and reuse connections where possible.
Responses from UBX public APIs
UBX public APIs return standard HTTP 1.1 response codes to describe the success or failure of the call. Some responses include a JSON payload.
Typically, UBX public APIs return responses as follows.
- 200 to 299: Success.
- 400-499: There is a problem with the API request. Examine the request for errors.
- 500-599: System error. Contact IBM for assistance.
Depending on the API method, the response can include a JSON payload. The APIs include various properties to provide customer identifiers and event attributes as part of the API call. In some cases, depending on the needs of the data destination endpoint, the response JSON might provide data
that is not required by the receiving endpoint. IBM recommends that receiving endpoints ignore extra data in the API response and process only the data that the endpoint requires.
Authentication key submission by UBX users
When business users want to add an endpoint their UBX accounts, they generate an authentication key in the UBX user interface. UBX requires that the UBX user submit the authentication key to the endpoint. You must create a method to accept the authentication
The authentication key is a 16-digit alphanumeric string that UBX generates when a UBX user adds an endpoint. Each authentication key is unique to a single endpoint for a single UBX user account. UBX users are required to create a new authentication key for each endpoint.
API calls to perform an action on behalf of a specific user account must provide the authentication key that the user generated in the UBX user interface. Such a key is referred to as an endpoint-level authentication key. IBM also makes account-level authentication keys available to IBM Commerce applications and to IBM Business Partners so that they can administer their endpoints in UBX. IBM never provides account-level authentication keys to UBX users.
As an endpoint provider, if your organization makes multiple endpoints available in UBX, your business systems must accommodate UBX marketing users who might provide multiple endpoint authentication keys.
- Account-level API
- Application API: Define applications
- Application API: Define event types for features
- Application API: Define features
- Application API: Define user access
- Application API: register endpoints
- Application APIs: Define application deployments
- Endpoint API: Custom Endpoints
- Event API
- Identity management APIs
- Jobs API
- Segment API