Identity management APIs

Suggest Edits

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 .

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

GET /v1/identityfilters

Get a list of the identity filters that exist on 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 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 account.

Example request (as a curl command):

cURL

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

Response

GET v1/identityfilters provides responses as follows.

JSON

Output (see notes below)

[
{
"endpointFilterId": <identity filter ID>,

A. Identify the filter

"endpointId": <endpointID>,

B. Identify the endpoint

"identifierName": "<name>",
"publishFilter": <true | false>,
"subscribeFilter": <true | false>
}
]

C. Describe the filter

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

A: Identify the filter

Property

Data type

Valid value

Description

endpointFilterID

string

ID value, as defined by

assigns a unique ID to each endpoint filter. Each filter limits syndication of a single identifier.

B. Identify the endpoint

Property

Data type

Valid value

Description

endpointId

string

ID value, as defined by

The ID of the endpoint for which the identity filter is defined.

C: Describe the filter

Property

Data type

Valid value

Description

identifierName

string

As defined in the Acoustic Exchange identity store

The name of the identifier that is filtered.

publishFilter

boolean

true | false

If true: processes the identifier as submitted by an event or audience source but does not send the identifier to any destination endpoint.

If false: the value for subscribeFilter must be
true.

subscribeFilter

boolean

true | false

If true: processes the identifier as submitted by an event or audience source but does not send the identifier to the endpoint that is specified by the endpointID property.

If false: the value for publishFilter must be
true.

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

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.

JSON

Output (see notes below)

[
{
"endpointFilterId": <identity filter ID>,

A. Identify the filter

endpointId": <endpointID>,

B. Identify the endpoint

"identifierName": "<name>",
"publishFilter": <true | false>,
"subscribeFilter": <true | false>
}
]

C. Describe the filter

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

A: Identify the filter

Property

Data type

Valid value

Description

endpointFilterId

string

ID value, as defined by .

assigns a unique ID to each endpoint filter. Each filter limits syndication of a single identifier.

B: Identify the endpoint

Property

Data type

Valid value

Description

endpointFilterId

string

ID value, as defined by .

assigns a unique ID to each endpoint filter. Each filter limits syndication of a single
identifier.

C. Describe the filter

Property

Data type

Valid value

Description

identifierName

string

As defined in the Acoustic Exchange identity store

The name of the identifier that is filtered.

publisherFilter

boolean

true | false

If true: processes the specified identifier as submitted by an event or audience source but does not send the identifier to any destination endpoint.

If false: the value for subscribeFilter must be
true.

subscribeFilter

boolean

true | false

If true: processes the specified identifier as submitted by an event or audience source but does not send the identifier to the endpoint that is specified by the
endpointID property.

If false: the value for publishFilter must be
true.

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

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

JSON

Requirements (see notes below)

[
{
"identifierName":"<name>",
"publishFilter":<true | false>,
"subscribeFilter":<true | false>
}
]

A. Describe the new filter

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.

Property

Data type

Valid value

Description

identifierName

string

The name of the identifier.

The identity name that was defined during event or endpoint registration.

publishFilter

boolean

true | false

If true: Acoustic Exchange processes the identifier when submitted by a source endpoint,
but Acoustic Exchange does not send the identifier to any destination endpoint.

If false: the value for subscribeFilter must be
true.

subscribeFilter

boolean

true | false

If true: Acoustic Exchange processes the identifier when submitted by a source endpoint,
but Acoustic Exchange does not send the identifier to the endpoint that is specified by the
endpointID property.

If false: the value for publishFilter must be
true.

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 account.

Example request (as a curl command):

cURL

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

JSON

Requirements (see notes below

[
{
"identifierName":"<name>",
"publishFilter":<true | false>,
"subscribeFilter":<true | false>
}
]

A. Describe the replacement filter filter

A: Describe the replacement filter

Property

Data type

Valid value

Description

identifierName

string

The name of the identifier.

The identity name that was defined during event or endpoint registration.

publishFilter

boolean

true | false

If true: Acoustic Exchange processes the identifier when submitted by a source endpoint,
but Acoustic Exchange does not send the identifier to any destination endpoint.

If false: the value for subscribeFilter must be true.

subscribeFilter

boolean

true | false

If true: processes the identifier when submitted by a source endpoint, but does not send the identifier to the endpoint that is specified by the
endpointID property.

If false: the value for publishFilter must be true.

DELETE /v1/identityfilters/{identifier}

Remove an identity filter from an endpoint.

About this API

You can remove identity filters that have been defined for endpoints. Call DELETE v1/identityfilters/{identifier} to remove an identity filter from an 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 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

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

Query parameter

Use

Description

identifier

Required

The name of the identifier that is filter by the identity filter that you want to remove.

Response

public APIs return standard HTTP 1.1 response codes.

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

Code

Description

200-299

True. The filter is deleted successfully from Acoustic Exchange.

400-499

There is a problem with the API request. Examine the request for errors.

For example:

401: Not authenticated
403: Not authorized

500-599

System error. Contact Support for assistance.

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 , 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 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):

HTML

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

Response

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):

Text

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

JSON

Description

"x1Id": "abc123_x1Id"

A. The name of the x1Id used in the call. An x1Id can hold up to 1000 unique identifiers.

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

B. The list of returned identifiers.

The list is composed of three parts: thename, value, and endpointId.

The name is the type of identifier that is returned.
The value is the unique identifier.
The endpointId shows which endpoint the identifier came from.

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 <base URL>/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):

Text

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

JSON

Description

"x1Id": "abc123_x1Id"

A. One of the x1Ids that was returned by the call. An x1Id can hold up to 1000 unique
identifiers.

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

B. The identifier that is used in the call.

The list is composed of three parts: thename, value, and endpointId.

The name is the type of identifier that is returned.
The value is the unique identifier.
The endpointId shows which endpoint the identifier came from.

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.

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

Updated 10 months ago