Application API: register endpoints

APIs that you call to register an endpoint that is based on a UBX application. You register endpoints on behalf of UBX users that request your endpoint in their UBX working environment.

To call APIs that register an endpoint on behalf of a UBX user, you must add the user-generated authentication key as the authorization bearer in the API call. The UBX user interface provides a way for users to generate the authentication key. You must provide a secure user interface or business practice to enable users to submit the key to you.

PUT /v1/endpoint/{applicationid}/{deploymentid}

Register an endpoint that is based on a UBX application on behalf of a UBX user.

About this API

Endpoints that are based on UBX applications can support multiple features and accommodate deployment on multiple data centers. Registering endpoints as application-based endpoints greatly enhances your ability to respond to customer needs and changes in the features that you can offer.

When you register an endpoint that is based on a UBX application you must specify the application ID and the deployment ID.

You must also be able to provide the authentication key that is generated by the UBX user on whose behalf you are registering your endpoint. The user generates the authentication key in their UBX interface. You provide the authentication key as the authorization bearer in the API request. Providing the user-generated authentication key verifies for UBX that the UBX user grants explicit permission for you to interact with UBX on the user’s behalf.

You must call this API separately for every UBX user that requests your endpoint for use in their UBX environment. You can call this API differently, depending on how you want to register the endpoint.

  • Register the endpoint and specify marketing database information that is different from what the UBX application defines and includes features that define various event types.
  • Register the endpoint and include only features that define various event types. For example, register one endpoint that provides event data for email messaging and another for events related to SMS messaging.
  • Register the endpoint only, without features or custom marketing database information.

Before you begin

Before you can register your endpoint as an endpoint provider on behalf of UBX users, you must complete the following steps. Typically, you perform these steps in advance for each type of endpoint that you provide. You then call PUT v1/endpoint/{applicationid}/{deploymentid} each time that a different UBX user requests that you register the endpoint.

Request

You must specify the endpoint-level authentication key that a UBX user generates in the UBX user interface. As the endpoint provider, you are responsible for providing the means for the user to submit the authentication key to you in a secure manner.

The base URL for the API request is the URL that IBM assigned to your account during the initial account provisioning process.

The application ID is the value that UBX generated when you created the application with the call to POST v1/application. The deploymentID is the value that you defined when you generated the feature by calling POST v1/application/<applicationID>/deployment.

The following example illustrates a request (using curl) to register an endpoint that uses the global definitions for marketing database, audience attributes and identifiers, and does not define features. To register the endpoint only, make the call with an empty request body.

curl -v 
-X PUT 
-H "Authorization: Bearer <user-generated endpoint-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/endpoint/{applicationid}/{deploymentid}

Register endpoint – custom marketing database properties and list of features

The following example illustrates the format of a complete JSON for registering an endpoint with custom marketing database properties and a list of features that are available from the endpoint. The features define event types that the endpoint can provide.

Request JSON – custom marketing database and list of features
{ 
  "marketingDatabasesDefinition": {
      "marketingDatabases": [
         {
         "id": <string>,
         "name": "<source database name>",
         "identifiers": [
            {
            "name": "<identifier name>",
            "type": "<identifier type>",
            "hashMode": <hashing requirement>,
            "hashAlgorithm": <algorithm type>,
            "isRequired": <true|false>
            "isCaseSensitive": <true|false>
            }
            ],
         "attributes": [
            {
            "name": "<attribute name>",
            "type": "<attribute type>",
            "hashMode": <hashing requirement>,
            "hashAlgorithm": <algorithm type>,
            "isRequired": <true|false>
            "isCaseSensitive": <true|false>
            },
         ]
      }
      ]
  },
  "features"  : [ "<feature name>","<feature name>" ]
}
Property Use Data type Valid value Description
marketingDatabases Optional The property definitions are the same as for PUT v1/ application.
However, you can define the properties differently from the application-level properties, if
necessary.
features Optional String Valid UBX feature name List of features that are available from the endpoint.

Register endpoint – list of features only

The following example illustrates the format of a complete JSON for registering an endpoint that uses the application-level marketing database properties and specifies a list of features that are available from the endpoint. The features define event types that the endpoint can provide.

Request JSON – custom marketing database and list of features
{  
 {
  "features"  : [ "<feature name>","<feature name>" ]
  }
}

Register endpoint – endpoint only

The following example illustrates the format of a complete JSON for registering an endpoint only. To register the endpoint only, make the call with an empty request body.

Request JSON – custom marketing database and list of features
{ }

Response

UBX public APIs return standard HTTP 1.1 response codes.

For a successful call, the response includes a JSON payload that matches the payload of the
request.

PUT /v1/endpoint/application

Register an endpoint that is based on a UBX application on behalf of a UBX user.

About this API

Endpoints that are based on UBX applications can support multiple features and accommodate deployment on multiple data centers. Registering endpoints as application-based endpoints greatly enhances your ability to respond to customer needs and changes in the features that you can offer.

When you register an endpoint using the PUT /v1/endpoint/application, UBX retrieves the application ID and the deployment ID from the endpoint definition.

You must be able to provide the authentication key that is generated by the UBX user on whose behalf you are registering your endpoint. The user generates the authentication key in their UBX interface. You provide the authentication key as the authorization bearer in the API request. Providing the user-generated authentication key verifies for UBX that the UBX user grants explicit permission for you to interact with UBX on the user’s behalf.

You must call this API separately for every UBX user that requests your endpoint for use in their UBX environment. You can call this API differently, depending on how you want to register the endpoint.

  • Register the endpoint and specify marketing database information that is different from what the UBX application defines and includes features that define various event types.
  • Register the endpoint and include only features that define various event types. For example, register one endpoint that provides event data for email messaging and another for events related to SMS messaging.
  • Register the endpoint only, without features or custom marketing database information.

Before you begin

Before you can register your endpoint as an endpoint provider on behalf of UBX users, you must complete the following steps. Typically, you perform these steps in advance for each type of endpoint that you provide. You then call PUT v1/endpoint/application each time that a different UBX user requests that you register the endpoint.

Request

You must specify the endpoint-level authentication key that a UBX user generates in the UBX user interface. As the endpoint provider, you are responsible for providing the means for the user to submit the authentication key to you in a secure manner.

The base URL for the API request is the URL that IBM assigned to your account during the initial account provisioning process.

The following example illustrates a request (using curl) to register an endpoint that uses the global definitions for marketing database, audience attributes and identifiers, and does not define features. To register the endpoint only, make the call with an empty request body.

curl -v 
-X PUT 
-H "Authorization: Bearer <user-generated endpoint-level authentication key>" 
-H "Content-Type: application/json" 
https://<base URL>/v1/endpoint/application

Register endpoint – custom marketing database properties and list of features

The following example illustrates the format of a complete JSON payload for registering an endpoint with custom marketing database properties and a list of features that are available from the endpoint. The features define event types that the endpoint can provide.

Request JSON – custom marketing database and list of features
{ 
  "marketingDatabasesDefinition": {
      "marketingDatabases": [
         {
         "id": <string>,
         "name": "<source database name>",
         "identifiers": [
            {
            "name": "<identifier name>",
            "type": "<identifier type>",
            "hashMode": <hashing requirement>,
            "hashAlgorithm": <algorithm type>,
            "isRequired": <true|false>
            "isCaseSensitive": <true|false>
            }
            ],
         "attributes": [
            {
            "name": "<attribute name>",
            "type": "<attribute type>",
            "hashMode": <hashing requirement>,
            "hashAlgorithm": <algorithm type>,
            "isRequired": <true|false>
            "isCaseSensitive": <true|false>
            },
         ]
      }
      ]
  },
  "features"  : [ "<feature name>","<feature name>" ]
}
Property Use Data type Valid value Description
marketingDatabases Optional The property definitions are the same as for PUT v1/ application.
However, you can define the properties differently from the application-level properties, if
necessary.
features Optional String Valid UBX feature name List of features that are available from the endpoint.

Register endpoint – list of features only

The following example illustrates the format of a complete JSON payload for registering an
endpoint that uses the application-level marketing database properties and specifies a list of
features that are available from the endpoint. The features define event types that the endpoint can
provide.

Request JSON – custom marketing database and list of features
{  
 {
  "features"  : [ "<feature name>","<feature name>" ]
  }
}

Register endpoint – endpoint only

The following example illustrates the format of a complete JSON payload for registering an endpoint only. To register the endpoint only, make the call with an empty request body.

Request JSON – custom marketing database and list of features
{ }

Response

UBX public APIs return standard HTTP 1.1 response codes.

For a successful call, the response includes a JSON payload that matches the payload of the request.

GET /v1/endpoint

Call GET /v1/endpoint with a user-generated endpoint-level authentication key to get a description of a specific endpoint that is registered with UBX. The description can include various endpoint characteristics that you specify as additional query parameters in the API call.

About this API

When UBX users register an endpoint, they generate an authentication key which is specific to the UBX user account and the registered endpoint. Calls to UBX APIs on behalf of a UBX user account must include this authentication key as the authorization bearer for the call.

When you call GET /v1/endpoint with an endpoint authentication key, UBX returns information that describes the single endpoint that is associated with the authentication key. In the URL for the call, you can include additional optional URL parameters to request specific endpoint characteristics. Separate parameters with &.

Request

Direct the API call to the base URL that is assigned to your UBX account.

The following example illustrates a request (using curl) to get information about an endpoint:

curl -v 
-X GET 
-H "Authorization: Bearer <user-generated endpoint-level authentication key>" 
https://<base URL>/v1/endpoint?<parameter 1>&<parameter 2>&<parameter n>

Note: the Authorization: Bearer must be an endpoint-level authentication key.  

For example, calling the following URL returns descriptions for up to 20 segments that provide audience data from the endpoint that is associated with the endpoint-authentication key.

https://<baseURL>/v1/endpoint?segment=true&source=true&
loadSegments=true&startRecord=1&pageSize=20

Query parameter Description
destination

Return descriptions of audience and event destination endpoints.

Example: destination=true

event

Return descriptions of event source and event destination
endpoints.

Example:event=true

loadEvents

Use with event. Return the known eventTypes for an event producer.

Example: event=true&loadEvents=true

loadSegments

Use with segment. Return the known segments for a segment producer.

Example: segment=true&loadSegments=true

pageSize

Pass an integer value for the maximum number of segments to return in the call response. Use with segment.

Example: segment=true&loadSegments=true& pageSize=10

searchByDescription

Pass a search criteria that might match a value in a segment description of a segment.

Example: searchByDescription=opt-in.

searchByName

Pass a search criteria that might match the name of a segment.

Example: searchByName=Recent opt-ins.

segment

Return descriptions of segment source and segment
destination endpoints.

Example:segment=true

source

Return descriptions of audience and event source endpoints.

Example: source=true

startRecord

Use with pageSize. Pass an integer to start at a given record in the matching
results.

Example: pageSize=10&startRecord=2

Response

UBX public APIs return standard HTTP 1.1 response codes.

DELETE /v1/endpoint

Delete a UBX endpoint for a specified UBX user account.

About this API

Call DELETE /v1/endpoint to remove the endpoint from the list of endpoints that appear as enabled and available to a specific UBX user account. In the API call, you must specify the authentication key that is associated with the UBX user.

Request

Direct the API call to the base URL that is assigned to your UBX account.

The following example illustrates a request (using curl) to remove endpoint information:

Request:
curl -v 
  -X DELETE
  -H "Authorization: Bearer <user-generated endpoint-level authentication key>" 
  -H "Content-Type: application/json" 
   https://<base URL>/v1/endpoint

Response

UBX public APIs return standard HTTP 1.1 response codes.

Join The Discussion

Your email address will not be published. Required fields are marked *