v1/identityFilters API
Use
GET /v1/identityfilters
Get a list of the identity filters that exist on
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
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
Example request (as a curl command):
curl -v
-X GET
-H "Authorization: Bearer 1234-abcd-5678-efgh"
<base URL>/v1/identityfilters
[
{
"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
endpointFilterID
string
ID value, as defined by
endpointId
string
ID value, as defined by
The ID of the endpoint for which the identity filter is defined.
C: Describe the filter
identifierName
string
As defined in the Acoustic Exchange identity store
The name of the identifier that is filtered.
publishFilter
boolean
true | false
If true:
If false: the value for subscribeFilter must be
true.
subscribeFilter
boolean
true | false
If true:
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 -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.
[
{
"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
endpointFilterId
string
ID value, as defined by
endpointFilterId
string
ID value, as defined by
identifier.
identifierName
string
As defined in the Acoustic Exchange identity store
The name of the identifier that is filtered.
publisherFilter
boolean
true | false
If true:
If false: the value for subscribeFilter must be
true.
subscribeFilter
boolean
true | false
If true:
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 -v
-X POST
-H "Authorization: Bearer 1234-abcd-5678-efgh"
-d ' [{"identifierName":"<identifier name>","publishFilter":<boolean>,
"subscribeFilter":<boolean>}]'
<base URL>/v1/identityfilters
[
{
"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.
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
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
[
{
"identifierName":"<name>",
"publishFilter":<true | false>,
"subscribeFilter":<true | false>
}
]
A. Describe the replacement filter filter
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:
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
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
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>}
identifier
Required
The name of the identifier that is filter by the identity filter that you want to remove.
Response
DELETE /v1/jobs/{jobId}/segmentDataFiles/{fileName} provides responses as follows.
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
Request
Direct the API call to the base URL that is assigned to your
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
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}
],
]
}
]
"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):
[
{
"x1Id": "abc123_x1Id",
"identifiers":
[
{"name": "Email"
"value": "[email protected]",
"endpointId": 123},
],
]
}
{
"x1Id": "def456_x1Id",
"identifiers":
[
{"name": "Email"
"value": "[email protected]",
"endpointId": 123},
],
]
}
]
"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.
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
Updated 10 months ago