POST /lookup/{collection-id}/keychain

Use the POST /lookup/{collection-id}/keychain endpoint to find a single profile in a profile collection by one or more keychain keys, such as an email address or loyalty ID. This endpoint behaves like GET /lookup/{collection-id}/keychain, but the keychain keys are sent in the request body. Use this endpoint when a key value should not appear in a query string.

Note

This endpoint is part of the Real-time API, an unstable API that may change without advance notice of breaking changes.

Note

In the Amperity user interface a profile collection is shown on the Profiles page. The value for {collection-id} identifies that profile collection.

Prerequisites

1. Add an API key.

2. Generate an access token.

3. A profile collection must be configured for your tenant. Before creating a profile collection, you must contact your Amperity representative to enable real-time product features.

Note

The access token must be granted the profile-collections:read and pii:read permissions.

Request URL

Direct all requests to the POST /lookup/{collection-id}/keychain endpoint to the request URL. The request URL uses the base URL with the endpoint path appended.

Amazon AWS

https://app.amperity.com/prof/lookup/{collection-id}/keychain

Microsoft Azure

https://{tenant-id}.amperity.com/prof/lookup/{collection-id}/keychain

You can find the tenant ID from the Amperity user interface. From the Settings page and select the Security tab. Under API keys, in the row for an API key, open the menu and select Copy tenant ID.

Rate limit

A rate limit is the number of requests that may be made to the Amperity API in a given time period.

Requests

A request to the POST /lookup/{collection-id}/keychain endpoint sends the keychain keys in a JSON request body. At least one key is required.

curl --request POST \
       'https://app.amperity.com/prof/lookup/{collection-id}/keychain' \
     --header 'amperity-tenant: {tenant-id}' \
     --header 'Authorization: Bearer {token}' \
     --header 'Content-Type: application/json' \
     --data '{ "keys": { "email": "customer@example.com" }, "enrich": false }'

This example is formatted for readability in a narrow page layout.

Request parameters

The following table describes the parameters that may be used with the POST /lookup/{collection-id}/keychain endpoint.

Parameter	Description
collection-id	String. Required. The ID of the profile collection to search.
keys	JSON object. Required. A map of keychain keys to values, such as { "email": "customer@example.com" }. At least one key is required.
enrich	Boolean. Optional. Set to true to include enriched attributes in the returned profile. Default value: false.

Responses

A response from the POST /lookup/{collection-id}/keychain endpoint will match an HTTP status code. A 200 response returns the matching profile. The Location header of a 200 response contains the URL for the matched profile.

200 OK

The 200 response returns the matching profile.

{
  "collection_id": "{collection-id}",
  "profile_id": "{profile-id}",
  "attributes": {
    "email": "customer@example.com"
  },
  "created_at": "{timestamp}",
  "updated_at": "{timestamp}",
  "ticked_at": "{timestamp}",
  "links": {
    "email": ["customer@example.com"],
    "phone": ["+15555550100"]
  }
}

Other responses

Status	Description
400	No keychain keys were provided. At least one key is required.
404	No matching profile was found in the profile collection.