GET /lookup/{collection-id}/keychain

Use the GET /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. Keychain keys are passed as query string parameters.

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 GET /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 GET /lookup/{collection-id}/keychain endpoint passes one or more keychain keys as query string parameters. At least one key is required.

Note

Query string values must be URL-encoded. This matters most for values containing a literal + character, which is otherwise decoded as a space. Alternatively, use the POST /lookup/{collection-id}/keychain endpoint to send keychain keys in the request body.

curl --request GET \
       'https://app.amperity.com/prof/lookup/{collection-id}/keychain?email=customer@example.com' \
     --header 'amperity-tenant: {tenant-id}' \
     --header 'Authorization: Bearer {token}'

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 GET /lookup/{collection-id}/keychain endpoint.

Parameter	Description
collection-id	String. Required. The ID of the profile collection to search.
keychain keys	String. Required. One or more keychain keys, passed as query string parameters in the form {key}={value}. For example: 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 GET /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.