Developers
Help CenterCommunityStatus

Register custom Acoustic Exchange endpoints

Suggest Edits

Step-by-step

1. Register an endpoint on behalf of an Exchange user.

In the case of a custom endpoint, the user must provide you with the authentication key that the user-generated in Exchange.

Call PUT /v1/endpoint to register the endpoint. This API organizes properties in several sections to define the endpoint characteristics.

Exchange users request your endpoint for use by their Exchange user account. You must include the authentication key that is provided by the Exchange user in each API call to Exchange.

2. Identify and describe the endpoint.

Provide information that Exchange requires to identify the endpoint and display it in the Exchange user interface.

Include the endpoint name, endpoint provider name, global URL for the endpoint, and the hashing algorithm that you use to obscure sensitive data.

Provide information that Exchange requires to identify the endpoint and display it in the Exchange user interface.

The URL that you define as part of the endpoint description is a global URL. When you define an endpoint type, you can define a different URL that takes precedence over the global URL.

As required, you can specify a hashing algorithm to obscure potentially sensitive identity and attribute data.

Exchange uses the information to present the endpoint in the Exchange user interface. Concise names and descriptions present your business solution in a positive light and make it easier for Exchange users to identify your solution in their Exchange workspace. Consult with the Exchange account provisioning team to plan how to present your endpoint in Exchange.

3. Enable event and audience sources and destinations.

You must enable the endpoint as a source and destination for events and audiences, depending what the endpoint can produce or consume.

For audience endpoints indicate whether the endpoint syndicates audience data as a push type or pull type of endpoint.

You must explicitly enable the endpoint as either a source or destination for event or audience data. You can also indicate how Acoustic Exchange exchanges audience data with the endpoint.

The endpoint can be any or all of the following endpoint types.

  • Event source
  • Event destination
  • Audience source
  • Audience destination

For audience endpoints, you must provide a value for either producerType or destinationType. You specify the type of data exchange as either push or pull.

For producerType (provides audience data)

  • Push: allows the endpoint to push audience data to Exchange.
  • Pull: Exchange pulls audience data and metadata from the endpoint, by using the global URL for the endpoint or the address that you specify with the URL property.

For destinationType (consumes audience data)

  • Push: allows Exchange to push audience data to the global URL for the endpoint or to the address that you specify with the URL property.
  • Pull: Exchange prepares and stores audience data for download and waits for the endpoint to retrieve the data.

4.Identify a marketing database for audience endpoints

Describe the source and schema of the source for identity lookup data for events and audiences.

You can describe the database that is the source and schema of the source for identity lookup data for events and audiences. Identifying the source of the audience data is optional.

If you identify the source database, you must provide the name of the database that provides the audience data.

5. Specify contact identifiers.

You can define one or more attributes that relate to a specific individual. You must specify the name of the identifier and type of data that the identifier provides. Over time, Exchange merges identity records of the same type for the same individual to provide a detailed view of the customer in multiple contexts.

You can specify attributes in the audience data that can be used to identify specific individuals. Exchange defines several recognized identifier types.

For example, if the audience data includes email addresses, you can specify the identifier type email.

Exchange uses identifier attributes to identify specific individuals in an audience. Over time, Exchange merges identity records of the same type for the same individual to provide a detailed view of the customer in multiple contexts. You can define one or more attributes that relate to a specific individual. You must specify the name of the identifier and type of data that the identifier provides.

To support augmenting audience identities, the type of identifier in the audience source must match the type of identifier in the destination. The names might be different, but the types must be same.

Because identifiers can sometimes reveal personally sensitive information, Exchange supports various hashing algorithms to obscure the data.

6. Specify audience attributes

Define or more attributes that describe at least some of the individuals that are present in the audience data.

You can specify attributes in the audience data that can be used to describe individuals in the audience data. The values of the attributes that you define here do not typically relate to only one individual in the audience data and therefore cannot be used as an identifier.

Specifying audience attributes is optional, but you can define or more attributes that describe at least some of the individuals that are present in an audience. In general, the more descriptive attributes that you can provide that more useful your endpoint becomes to Exchange users who look to combine information from various endpoints to address their business objectives.

If you specify audience attributes, you must provide an attribute name and specify the data type of the attribute value.

Because audience attributes can sometimes reveal personally sensitive information, Exchange supports various hashing algorithms to obscure the data.

7. Define secure endpoint access.

Call PUT /v1/endpointattributes to provide Exchange with authentication credentials and connection information that Exchange can use to construct secure, automatic connections to endpoints.

The user-generated authentication key is required as a URL parameter and as the authorization bearer in the header of the call.

To enable Exchange to communicate automatically with endpoints that impose specific connection and authentication requirements, Exchange provides the v1/endpointattributes API to supply the required credentials. Call this API to provide Exchange with the information it needs to construct secure connections to endpoints.

Register the endpoint by calling PUT v1/endpoint.

Note: Authentication key that you received from the Exchange user. The authentication key is provided in the header of the call to PUT v1/endpoint to register the endpoint.

Some source or destination endpoints require specific authentication credentials and connection information to allow Exchange to exchange information with the endpoint application. Endpoints that require an authenticated connection must call v1/endpointattributes to provide Exchange with the connection and login information. Exchange uses the information it receives to properly form a secure connection to the endpoint without the need for human intervention.

The call to v1/endpointattributes provides the endpoint authentication and connection information as attributes in the JSON payload of the API request. The specific attributes and values that the call provides depend on the requirements of each endpoint.

Calling v1/endpointattributes requires the authentication key that was used to register the endpoint with Exchange. The authentication key is unique to the endpoint and the specific Exchange account that requested that the endpoint registration. The authentication key is required in the URL of the call and as the authorization bearer in the header of the call.

The call to v1/endpointattributes is made as a PUT call. The PUT call is used to add new endpoint connection and authentication attributes and to update existing attributes. Calling v1/endpointattributes more than once overwrites information that was provided by the previous call.

Exchange retrieves the information that you provide in calls to v1/endpoint attributes nightly. As a result, Exchange cannot construct an automated connection to an endpoint immediately after you call v1/endpoint. You must wait until the following day to verify that Exchange can automatically construct a secure connection to the endpoint.

  1. Call the v1/endpointattributes API. For details about the API, see Exchange PUT /v1/endpointattributes.
  2. In the header of the call, use the authentication key that you used as the authentication bearer in the call to v1/endpoint as the authentication bearer in the call to v1/endpointattributes.
  3. Direct the API call to: https://api-campaign-us-1.goacoustic.com/v1/endpointattributes/authkey/””
  4. Specify the connection and access details as attributes in the JSON payload of the request. The attribute names and values depend on the specific access and connection requirements of the endpoint. 
{
"attributes":
 {"accessID":"30000001",
 "user":"marketnow",
 "password":"pw!321#bsh", 
 "dataimportUrl":"https://import.example.com/eb/aud001/1.0/api.do"
 } 
}

Examples:

Acoustic Campaign as an audience producer

This example illustrates how to configure v1/endpointattributes to provide Exchange with the login and connection information it requires to receive audience data from Campaign. corresponds to the number of the Campaign pod to which your organization is assigned. For example, if your organization uses Campaign pod1, the value for xmlAPIUrl is http://api-campaign-us-1.goacoustic.com/. The refresh token is the refresh token provided by Campaign for your organization.

PUT v1/endpointattributes
 
{
 "podUrl" : "http://api<number>.silverpop.com/,
 "refreshToken" : "<account-specific refresh token>"
}

Digital Analytics as an audience source

This example illustrates how to configure v1/endpointattributes to provide Exchange with the login and connection information that it requires to receive audience data from Digital Analytics.

{
 "clientID" : "<clientID>",
 "user": "<Digital Analytics user name>",
 "password":"<Digital Analytics password>",
 "exportAPIUrl":"https://export.coremetrics.com/eb/segmentapi/1.0/api.do"
}

Facebook as an audience source

This example illustrates how to configure v1/endpointattributes to provide Exchange with the login and connection information that it requires to download audience data to Facebook. accessToken: The user must generate an access token for Exchange to use to access the user’s Facebook account. clientID: This value is required so that Exchange can automatically renew the accessToken. clientSecret: This value is also required so that Exchange can automatically renew the accessToken.

{
 "redirectURI":"http://localhost:8080/WebApplication1/NewServlet",
 "adAccountID":"<accountID>",
 "accessToken":"<access token>",
 "clientID":"<facebook client ID>",
 "clientSecret":"<facebook client secret>" //
}

8. Ready for use.

The requesting Exchange user sees the endpoint status change from Pending to Active.

Updated over 3 years ago