Identity management APIs

Acoustic Exchange provides a two types of identity management APIs, identity and identityFilters. You can use the identity management APIs to manage identity data that is distributed by Exchange.

v1/identityFilters API
Use Exchange identityFilters API to manage identity data that is distributed by Exchange.

GET /v1/identityfilters

Get a list of the identity filters that exist on Exchange for an endpoint.

About this API

You can define identity filters to prevent specified identifiers from being sent to destination endpoints. Call GET v1/identityfilters to get details for one or more identity filters that exist in Exchange for the endpoint that is associated with the authentication key that is used as the authorization bearer for the API call.

The response separately identifies each identity filter, the identifier that is filtered, and indicates whether the filter applies to all destination endpoints, or to a specific destination endpoint.

Request

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

Example request (as a curl command):

curl -v 
  -X GET 
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  <base URL>/v1/identityfilters

Response

GET v1/identityfilters provides responses as follows.

Repeat the JSON for each filter that is defined for the endpoint.

A: Identify the filter

B. Identify the endpoint

C: Describe the filter

GET /v1/identityfilters/{identifierName}

Get the identity filter that exists on an endpoint for a specific identifier.

About this API

You can define identity filters to prevent specified identifiers from being sent to destination endpoints. Call GET v1/identityfilters/{identifierName} to get details for a specific identity filter that exists on an endpoint that is associated with the authentication key
that is used as the authorization bearer for the API call.

When you include a specific identifier as a URL parameter in the API call, the response provides details for the specific identity filter.

Request

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

Example request (as a curl command):

curl -v 
  -X GET 
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  <base URL>/v1/identityfilters/{identifier name}

Response

GET v1/identityfilters/{identifierName} provides a response as follows. The response provides details for a single identity filter.

If there are no filters on the endpoint for the identifier that you specify, the API returns 400 - Invalid request.

Repeat the JSON for each filter that is defined for the endpoint.

A: Identify the filter

B: Identify the endpoint

C. Describe the filter

POST /v1/identityfilters

Add one or more identity filters to Acoustic Exchange for an endpoint.

About this API

You can define identity filters to prevent specified identifiers from being sent to destination endpoints. Call POST v1/identityfilters to add one or more identity filters to Acoustic Exchange for the endpoint that is associated with the authentication key that is used as the authorization bearer for the API call.

When you make the API call, you specify the name of the identifier that is filtered.

Request

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

Example request (as a curl command):

curl -v 
  -X POST 
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  -d ' [{"identifierName":"<identifier name>","publishFilter":<boolean>,
      "subscribeFilter":<boolean>}]' 
  <base URL>/v1/identityfilters

A: Describe the new filter

Specify the name of the identifier that you want to change. When you make the call, you can
change the whether the filter applies to all destination endpoints or to a single endpoint.

PUT /v1/identityfilters

Change an identity filter for an endpoint.

About this API

You can define identity filters to prevent specified identifiers from being sent to destination endpoints. Call PUT v1/identityfilters to replace an identity filter that is defined for the endpoint that is associated with the authentication key that is used as the authorization bearer for the API call.

Request

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

Example request (as a curl command):

curl -v 
  -X PUT 
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  -d ' [{"identifierName":"<identifier name>","publishFilter":<boolean>,
      "subscribeFilter":<boolean>}]' 
  <base URL>/v1/identityfilters

A: Describe the replacement filter

DELETE /v1/identityfilters/{identifier}

Remove an identity filter from an endpoint.

About this API

You can remove identity filters that have been defined for Acoustic Exchange endpoints. Call DELETE v1/identityfilters/{identifier} to remove an identity filter from an Exchange for the endpoint that is associated with the authentication key that is used as the authorization bearer for the API call.

You must remove identity filters individually by making a separate DELETE call for each filter that you want to remove.

Request

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

Specify the filter to remove by entering the identifier name as a URL parameter.

Specify the endpoint that defines the filter by providing the authentication key that is associated with the endpoint as the authorization bearer in the API call.

Example request (as a curl command):

curl -v 
  -X DELETE 
  -H "Authorization: Bearer 1234-abcd-5678-efgh" 
  <base URL>/v1/identityfilters/{<identifier name>}

Response

Exchange public APIs return standard HTTP 1.1 response codes.

DELETE /v1/jobs/{jobId}/segmentDataFiles/{fileName} provides responses as follows.

v1/identity API

Use the identity API to manage identity data associated with an x1Id.

GET v1/identity/{x1Id}

Use the GET v1/identity/{x1Id} API to return all identifiers that are associated with an x1Id.

About this API

In Exchange, an x1Id acts as a repository for unique customer identifiers that can be associated with a particular individual. There can be some scenarios where you want to examine different identifiers within an x1Id. For example, if a mistake was made during the event publishing process and that mistake caused an identifier to be associated with an x1Id in error, you can use this API so review its identifiers.

Request

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

You must use an endpoint-level authorization key as the authorization bearer in this API call.

Example request (values are presented for example only):

GET <base URL>/v1/identity/{abc123_x1Id}

Response

Exchange public APIs return standard HTTP 1.1 response codes.

GET v1/identity/{x1Id} returns descriptive information for the x1Id that you specified.

Example response (values are presented for example only):

[
   {
     "x1Id": "abc123_x1Id",
     "identifiers":
     [
      {"name": "Email"
       "value": "[email protected]",
       "endpointId": 123},
      {"name": "cookieId",
       "value": "455739626"
       "endpointId": 123},
      {"name": "userId",
       "value": "ub0N4DZ5678NW"
       "endpointId": 123}
      ],
     ]
   }
]

What to do next

If you have found a specific identifier that is less than accurate, or you believe it be it was
uploaded in error, you can use the GET
/identity?{identifierName}={identifierValue}[&endpointId={endpointId}] API to return a list of all the x1Ids that identifier is associated.

GET v1/identity?{identifierName}={identifierValue}[&endpointId={endpointId}]

You can use the GET v1/identity/?{identifierName}={identifierValue}[&endpointId={endpointId}] to return all of the x1Ids that are associated with a specific identifier.

About this API

In Acoustic Exchange, an x1Id acts as a repository for unique customer identifiers that can be associated with a particular individual.

If a mistake or error is made when you are publishing an identifier to Acoustic Exchange in an event, Acoustic Exchange‘s identity matching service might not function properly. This is due to x1Ids retaining inaccurate or problematic data.

If you suspect that an inaccurate or problematic identifier is associated with more than one x1Id, you can use this API to find that single identifier across all x1Ids associated with an endpoint.

Request

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

You must use an endpoint-level or an account-level authorization key as the authorization bearer in this API call.

If you use an account-level authorization key, you must provide an endpointId as a query parameter in the request URL.

Example request (values are presented for example only):
GET /v1/identity?{Email}={[email protected]}[&endpointId={123}]

Response

Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

GET
v1/identity?{identifierName}={identifierValue}[&endpointId={endpointId}] returns descriptive information for the identifier and endpointId that you specified.

Example response (values are presented for example only):

[
   {
     "x1Id": "abc123_x1Id",
     "identifiers":
     [
      {"name": "Email"
       "value": "[email protected]",
       "endpointId": 123},
      ],
     ]
   }
   {
     "x1Id": "def456_x1Id",
     "identifiers":
     [
      {"name": "Email"
       "value": "[email protected]",
       "endpointId": 123},
      ],
     ]
   }
]

What to do next

If you have determined that there is a problematic identifier associated with one or more x1Ids,
you can delete it by using the DELETE
v1/identity?{identifierName}={identifierValue}[&endpointId={endpointId}].

DELETE v1/identity?{identifierName}={identifierValue}[&endpointId={endpointId}]
Use the DELETE v1/identity?{identifierName}={identifierValue}[&endpointId={endpointId}] API to delete an identifier from all x1Ids associated with an endpoint.

Before you begin

Ensure that you have the correct name identifier that you want to delete. Deleting an identifier removes it from all x1Ids and endpoints that are associated with your application.

To get a list of identifiers associated with a specific x1Id, call
GET v1/identity/{x1Id}. For more information about this API, see GET v1/identity/{x1Id}.

To get a list of x1Ids that contain that are associated with a specific identifier, call GET v1/identity/?{identifierName}={identifierValue}[&endpointId={endpointId}].

For more information about this API, see GET v1/identity/?{identifierName}={identifierValue}[&endpointId={endpointId}]

About this API

In Acoustic Exchange, an x1Id acts as a repository for unique customer identifiers that can be associated with a particular individual.

If a mistake or error is made when you are publishing an identifier to Acoustic Exchange in an event, Acoustic Exchange‘s identity matching service might not function properly. This is due to x1Ids retaining inaccurate or problematic data.

To resolve this issue, you can delete the identifier from all x1Ids and endpoints that are associated with your application by calling the DELETE v1/identity?{identifierName}={identifierValue}[&endpointId={endpointId}] API.

Request

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

You must use an endpoint-level or an account-level authorization key as the authorization bearer in this API call.

If you use an account-level authorization key, you must provide an endpointId as a query parameter in the request URL.

Example request (values are presented for example only):
DELETE v1/identity?{Email}={[email protected]}[&endpointId={123}]
Response
Acoustic Exchange public APIs return standard HTTP 1.1 response codes.

DELETE
v1/identity?{identifierName}={identifierValue}[&endpointId={endpointId}] provides descriptive information in addition to the response code.

Example response:
A number of updated Identities: 1