Configure destinations for Eagle Eye

Eagle Eye is a loyalty and promotions platform. Its AIR platform manages loyalty wallets that track each customer’s earning and spending activity in a loyalty program.

The Eagle Eye connector sends loyalty identities from Amperity into loyalty wallets in the Eagle Eye AIR platform, performing one wallet operation for each person on every run.

Each row in the query results is one wallet operation, addressed by the person’s loyalty identity. There is no audience or list concept: Amperity does not keep a list in sync on the Eagle Eye side, it performs the configured operation for each person each time it runs. Amperity sends every row in the query results on each run; there is no incremental sync.

Two columns are sent, and the query that feeds the orchestration must produce them by name. The identity_value column (required) carries the person’s loyalty identity in Eagle Eye — a loyalty card number, email, or whatever identity type your company unit is configured for — and is the value every operation is addressed by. The friendly_name column (optional) is a human-readable label for the wallet: the create operation applies it to a new wallet when it is present, and the update operation exists to change it and requires it. Column names are matched without regard to capitalization.

The create operation can also attach other identities to each wallet and enroll each person in loyalty schemes, using more columns named after the Additional identity types and Loyalty scheme IDs settings. See Additional identities and loyalty schemes.

Every value is sent to Eagle Eye as text. An integer column, such as a card number stored as a number, is sent as its digits. Floating-point columns are not supported for identity values, because large numbers are written in scientific notation (for example 1.0E10) rather than as the card number. Cast such columns to a string or an integer in the query.

Important

The connector reads the loyalty identity from a column named identity_value — not from the Identity type setting. These are two different things and are easy to confuse:

• The Identity type setting names the Eagle Eye identity type your company unit uses (for example CUSTOMER_ID). You set it once on the destination.

• The identity_value column carries the identity values, one per row. The query results must include a column with this exact name (capitalization does not matter).

If your query outputs the values under a different column name, alias it to identity_value — for example SELECT loyalty_card_number AS identity_value. A send whose query results have no identity_value column fails before any wallet is sent, with a message naming the missing column.

Note

This destination uses the Eagle Eye AIR Wallet API .

Beta

The Eagle Eye connector is in beta. Contact your Amperity representative to learn more.

Important

Eagle Eye provisions your API credentials and configures each company unit. Before you configure the destination, get the Client ID, Client secret, and regional API URL from your Eagle Eye account manager, and confirm the Identity type name your unit uses and the behavioral state values your unit accepts for wallets and for identities — these are separate value sets that need not overlap. A state value your unit does not recognize is rejected. If you attach more identity types or enroll people in loyalty schemes, also confirm those identity type names, your unit’s loyalty scheme IDs, and the state values it accepts for scheme accounts, which are a third, separate value set.

Note

Wallet state and identity state were previously a single setting. If you set a state value on this destination before they were separated, that value now applies to New wallet state only. If it is an identity-namespace value — and your create sends were failing as a result — move it to New identity state.

Note

The Eagle Eye Wallet API has no bulk endpoint, so Amperity sends one request per person. Amperity paces requests at about five requests per second — an Amperity-side default, not a limit published by Eagle Eye — so a large send can take a long time (for example, a send of 100,000 people runs for several hours).

Wallet operations

The Wallet operation setting selects what each row does, and a send performs a single operation for the entire run. You choose the operation, and the state used by state-change, when you configure the orchestration that sends to this destination.

Operation	What it does
create	Provisions a wallet for each person and attaches their loyalty identity. This is the default. If the friendly_name column is present, its value is set as the new wallet’s label. When Additional identity types or Loyalty scheme IDs is set, it also attaches the person’s other identities and enrolls them in their loyalty schemes. A person who already has a wallet is recovered rather than duplicated, so re-sending the same query results is safe, and a re-send attaches anything the wallet is still missing.
update	Changes a wallet’s friendly name. Requires the friendly_name column.
state-change	Changes a wallet’s behavioral state. Requires the Wallet state setting.
suspend	Temporarily halts a wallet’s activity. Reversible with activate.
activate	Returns a suspended or inactive wallet to service.
terminate	Permanently closes a wallet. It cannot be undone, and Eagle Eye rejects any later change to a terminated wallet. It is the recommended operation for a consent-driven hard opt-out.
delete	A soft delete on Eagle Eye’s side: removes the wallet from active use but does not erase it. Intended for cleaning up test data, not for consent or data-subject requests — use terminate for those.

Every operation other than create first looks up the person’s existing wallet by their identity value. A person with no wallet yet is reported as a failed row and the run continues.

Additional identities and loyalty schemes

The create operation can attach more than one identity to each wallet, such as a customer ID, a loyalty card, and an email address, and can enroll each person in one or more loyalty schemes. Two optional destination settings list what to attach, and the query results carry one column for each listed item:

Column	Required	What it holds
identity_value_<type>	Yes, for create, one for each type in Additional identity types	The person’s identity value of that type, for example identity_value_card for CARD. A blank value means the person has no identity of that type.
identity_state_<type>	No	The state for that identity, from your unit’s identity-state values. A blank value lets Eagle Eye apply that identity type’s default state.
scheme_state_<id>	Yes, for create, one for each ID in Loyalty scheme IDs	The person’s account state in that loyalty scheme, for example scheme_state_1234567, from your unit’s scheme-account state values. A state enrolls the person in the scheme in that state. A blank value means the person is not enrolled in that scheme.

The identity type or scheme ID is written in lower case in the column name, and column names are matched without regard to capitalization. The columns must be present in the query results for the create operation, but individual values may be blank. Every other operation ignores them.

For example, with Identity type set to CUSTOMER_ID, Additional identity types set to CARD,EMAIL, and Loyalty scheme IDs set to 1234567, where points_scheme_state holds each person’s scheme-account state:

SELECT
  customer_id AS identity_value
  ,loyalty_card_number AS identity_value_card
  ,email AS identity_value_email
  ,points_scheme_state AS scheme_state_1234567
FROM Customer_360

How each send behaves

• New people. Amperity creates the wallet with all of the person’s identities and scheme accounts in a single request.

• People who already have a wallet. Amperity attaches the identities and scheme accounts the wallet is missing, and leaves the ones it already has. To add identities or schemes to existing wallets, add the columns and send with the create operation again.

• Changed states. When a person already has a scheme account or an identity, and the query results give it a different state, Amperity changes the state in Eagle Eye. A blank value never changes anything, so a blank scheme column never removes a person from a scheme. The state of the main identity comes from the New identity state setting and applies to new wallets only.

• Identity values. Eagle Eye compares identity values without regard to capitalization, and so does Amperity. A value repeated across a person’s identity columns is sent once.

When Eagle Eye rejects part of a person’s wallet

If Eagle Eye saves the wallet but will not attach one of the person’s identities (for example, because the value already belongs to another wallet, or the identity type is not configured for your unit), will not enroll them in a scheme (for example, because the scheme ID is unknown or the state is not accepted), or will not change a state, the row still counts as succeeded. The reason is listed in the error log for the run, naming the identity type or scheme ID, and never the identity value. Correct the setting or the values, and then send again with the create operation to attach what is still missing.

Note

Eagle Eye keeps the identity values of a deleted wallet reserved, so a person whose wallet was deleted cannot receive a new wallet with the same identity value. When Amperity confirms this, the row fails with a message saying that the identity belongs to a deleted wallet and cannot be reused.

Note

Sending to people who already have a wallet takes a few more requests per person than creating new wallets, because Amperity checks what each wallet already has before attaching anything.

Get details

Review the following details before configuring credentials for Eagle Eye and before configuring Amperity to send loyalty identities to loyalty wallets in the Eagle Eye AIR platform.

	Credential settings Required All three credential fields are required. No call can be made without them. Client ID The Eagle Eye AIR API client ID, provisioned by your Eagle Eye account manager. It identifies your Amperity integration to Eagle Eye. Client secret The Eagle Eye AIR API secret paired with the Client ID, provisioned by your Eagle Eye account manager. Amperity uses it to authenticate each request. API URL The Eagle Eye AIR Wallet API base URL for your region and environment. Select the URL that matches your Eagle Eye company unit: https://wallet.uk.eagleeye.com/2.0/ (United Kingdom) https://wallet.sandbox.uk.eagleeye.com/2.0/ (United Kingdom sandbox) https://wallet.au.eagleeye.com/2.0/ (Australia) https://wallet.us2.eagleeye.com/2.0/ (United States, US2) Confirm the correct URL with your Eagle Eye account manager. Defaults to the Australia URL.
	Required configuration setting Identity type The name your Eagle Eye company unit uses for the loyalty identity carried in the identity_value column — for example CUSTOMER_ID or a loyalty card type. This is configured in Eagle Eye and differs by company unit, so confirm the exact name with your Eagle Eye account manager. Every wallet operation is addressed by this identity. This setting names the identity type only; it does not name the query column. The identity values themselves must travel in a column named identity_value in the query results.
	Optional destination settings Wallet type The Eagle Eye wallet type created for new wallets by the create operation. Defaults to CONSUMER, Eagle Eye’s standard consumer wallet type. Change it only if your Eagle Eye company unit uses a different wallet type. New wallet state The Eagle Eye behavioral state applied to each new wallet by the create operation. It sets the wallet’s state only; the loyalty identity attached to the wallet takes its state from the New identity state setting. Wallet states and identity states are separate value sets, each configured per Eagle Eye company unit, so set this only to a wallet-state value your Eagle Eye account manager has confirmed for your unit; a value your unit does not recognize is rejected. Leave it unset to let Eagle Eye apply your unit’s default wallet state — the safest choice. New identity state The Eagle Eye behavioral state applied to the loyalty identity attached to each new wallet by the create operation. Identity states are a separate set of values from wallet states, each configured per Eagle Eye company unit, so set this only to an identity-state value your Eagle Eye account manager has confirmed for your unit; a value your unit does not recognize is rejected. Leave it unset to let Eagle Eye apply your unit’s default identity state — the safest choice. Additional identity types A comma-separated list of Eagle Eye identity type names to attach to each wallet in addition to the Identity type, for example CARD,EMAIL. List each type once, in upper case, exactly as your Eagle Eye company unit names it, and do not repeat the Identity type itself. For each listed type, the create operation reads the identity value from a column named identity_value_<type> and an optional state from a column named identity_state_<type>, with the type in lower case. For example, CARD reads identity_value_card and identity_state_card. A blank value means the person has no identity of that type. Leave this setting unset to attach only the Identity type. Loyalty scheme IDs A comma-separated list of Eagle Eye loyalty scheme IDs that new wallets can be enrolled in, for example 1234567,2345678. Each ID may contain letters, digits, and underscores, and is listed once. Get your unit’s scheme IDs from your Eagle Eye account manager. For each listed scheme, the create operation reads the scheme account state from a column named scheme_state_<id>, for example scheme_state_1234567. A state in that column enrolls the person in the scheme in that state. A blank value means the person is not enrolled in that scheme. Scheme account states are a third set of values, separate from wallet states and identity states, configured per Eagle Eye company unit, so use only a scheme-account state your Eagle Eye account manager has confirmed for your unit; a value your unit does not recognize is rejected. Leave this setting unset to create wallets without scheme accounts.
	Orchestration settings These are chosen for each orchestration that sends to this destination, not on the destination itself. Wallet operation The wallet operation performed for every row in the send. A send performs a single operation for the entire run: create (the default) provisions a wallet for each person and attaches their loyalty identity, and sets the wallet’s label from the friendly_name column when it is present. When Additional identity types or Loyalty scheme IDs is set, it also attaches the person’s other identities and enrolls them in their loyalty schemes. A person who already has a wallet is recovered rather than duplicated, so re-sending the same query results is safe, and a re-send attaches anything the wallet is still missing. update changes a wallet’s friendly name, and requires the friendly_name column. state-change changes a wallet’s behavioral state, and requires the Wallet state setting below. suspend temporarily halts a wallet’s activity, and activate returns a suspended or inactive wallet to service. terminate permanently closes a wallet — it cannot be undone, and Eagle Eye rejects any later change to a terminated wallet. It is the recommended operation for a consent-driven hard opt-out. delete is a soft delete on Eagle Eye’s side: it removes the wallet from active use but does not erase it. Intended for cleaning up test data, not for consent or data-subject requests — use terminate for those. Every operation other than create first looks up the person’s existing wallet by their identity value; a person with no wallet yet is reported as a failed row and the run continues. You choose this operation when you configure the orchestration that sends to this destination. Wallet state The behavioral state applied to the wallet by the state-change operation. This value comes from the wallet-state set — the same set as New wallet state, not the identity set — because state-change patches the wallet. Wallet states and identity states are separate value sets, so use only a wallet-state value your Eagle Eye account manager has confirmed for your unit. Required when the operation is state-change; Amperity stops the run with a message if it is missing. You choose this when you configure the orchestration that sends to this destination.

Configure credentials

Configure credentials for Eagle Eye before adding a destination.

An individual with access to Eagle Eye should use SnapPass to securely share “Client ID”, “Client secret”, and “API URL” details with the individual who configures Amperity.

To configure credentials for Eagle Eye

	From the Settings page, select the Credentials tab, and then click the Add credential button.
	In the Create credential dialog box, do the following: From the Plugin dropdown, select “Eagle Eye”. Assign the credential a name and description that ensures other users of Amperity can recognize when to use this destination.
	The settings that are available for a credential vary by credential type. For the “eagle-eye” credential type, configure settings, and then click Save. Required All three credential fields are required. Client ID The Eagle Eye AIR API client ID, provisioned by your Eagle Eye account manager. It identifies your Amperity integration to Eagle Eye. Client secret The Eagle Eye AIR API secret paired with the Client ID, provisioned by your Eagle Eye account manager. Amperity uses it to authenticate each request. API URL The Eagle Eye AIR Wallet API base URL for your region and environment. Select the URL that matches your Eagle Eye company unit: https://wallet.uk.eagleeye.com/2.0/ (United Kingdom) https://wallet.sandbox.uk.eagleeye.com/2.0/ (United Kingdom sandbox) https://wallet.au.eagleeye.com/2.0/ (Australia) https://wallet.us2.eagleeye.com/2.0/ (United States, US2) Confirm the correct URL with your Eagle Eye account manager. Defaults to the Australia URL.

Add destination

Use a sandbox to configure a destination for Eagle Eye. Before promoting your changes, send a sample audience, and then verify the results in Eagle Eye. After verifying the end-to-end workflow, push the destination from the sandbox to production.

To add a destination for Eagle Eye

	Open the Destinations page, select the New destinations button, and then select Orchestration. To configure a destination for Eagle Eye, do one of the following: Click the row in which Eagle Eye is located. Destinations list alphabetically and you can scroll up and down the list. Search for Eagle Eye. Start typing “eag”. The list filters to show only matching destinations. Select “Eagle Eye”.
	Select the credential for Eagle Eye from the Credential dropdown, and then click Continue. Tip Amperity validates the connection when the destination is saved. If the connection cannot be validated, an error is shown and the destination is not saved.
	In the “Destination settings” dialog box, assign the destination a name and description that ensures other users of Amperity can recognize when to use this destination. Configure business user access By default a destination is available to all users who have permission to view personally identifiable information (PII). Enable the Admin only checkbox to restrict access to only users assigned to the Datagrid Operator and Datagrid Administrator policies. Enable the PII setting checkbox to allow limited access to PII for this destination. Use the Restrict PII access policy option to prevent users from viewing data marked as PII anywhere in Amperity and from sending data to downstream workflows.
	Configure the following settings, and then click “Save”. Identity type The name your Eagle Eye company unit uses for the loyalty identity carried in the identity_value column — for example CUSTOMER_ID or a loyalty card type. This is configured in Eagle Eye and differs by company unit, so confirm the exact name with your Eagle Eye account manager. Every wallet operation is addressed by this identity. This setting names the identity type only; it does not name the query column. The identity values themselves must travel in a column named identity_value in the query results. Wallet type The Eagle Eye wallet type created for new wallets by the create operation. Defaults to CONSUMER, Eagle Eye’s standard consumer wallet type. Change it only if your Eagle Eye company unit uses a different wallet type. New wallet state The Eagle Eye behavioral state applied to each new wallet by the create operation. It sets the wallet’s state only; the loyalty identity attached to the wallet takes its state from the New identity state setting. Wallet states and identity states are separate value sets, each configured per Eagle Eye company unit, so set this only to a wallet-state value your Eagle Eye account manager has confirmed for your unit; a value your unit does not recognize is rejected. Leave it unset to let Eagle Eye apply your unit’s default wallet state — the safest choice. New identity state The Eagle Eye behavioral state applied to the loyalty identity attached to each new wallet by the create operation. Identity states are a separate set of values from wallet states, each configured per Eagle Eye company unit, so set this only to an identity-state value your Eagle Eye account manager has confirmed for your unit; a value your unit does not recognize is rejected. Leave it unset to let Eagle Eye apply your unit’s default identity state — the safest choice. Additional identity types A comma-separated list of Eagle Eye identity type names to attach to each wallet in addition to the Identity type, for example CARD,EMAIL. List each type once, in upper case, exactly as your Eagle Eye company unit names it, and do not repeat the Identity type itself. For each listed type, the create operation reads the identity value from a column named identity_value_<type> and an optional state from a column named identity_state_<type>, with the type in lower case. For example, CARD reads identity_value_card and identity_state_card. A blank value means the person has no identity of that type. Leave this setting unset to attach only the Identity type. Loyalty scheme IDs A comma-separated list of Eagle Eye loyalty scheme IDs that new wallets can be enrolled in, for example 1234567,2345678. Each ID may contain letters, digits, and underscores, and is listed once. Get your unit’s scheme IDs from your Eagle Eye account manager. For each listed scheme, the create operation reads the scheme account state from a column named scheme_state_<id>, for example scheme_state_1234567. A state in that column enrolls the person in the scheme in that state. A blank value means the person is not enrolled in that scheme. Scheme account states are a third set of values, separate from wallet states and identity states, configured per Eagle Eye company unit, so use only a scheme-account state your Eagle Eye account manager has confirmed for your unit; a value your unit does not recognize is rejected. Leave this setting unset to create wallets without scheme accounts.
	After configuring this destination users may use orchestrations to send query results Eagle Eye.
	Validate the audience with Eagle Eye by using a sample audience with a very small membership. For example: 10 or 100 members or the minimum audience size recommended by Eagle Eye. Send the sample audience to Eagle Eye and verify the sample audience is correct in Eagle Eye. Make adjustments if necessary. Only send full audiences after validation is complete.

Data validation

Amperity performs the configured operation for every row in the query results, except for rows it cannot process. A row is reported as failed, and the run continues, when any of the following is true:

• The identity_value column is empty for that row.

• The operation is update and the friendly_name column is empty for that row.

• The operation is anything other than create and Eagle Eye has no wallet for that row’s identity value.

• Eagle Eye rejects that row’s wallet payload, or the row targets a wallet that has already been terminated.

• Eagle Eye reports a conflict, or a locked wallet, for that row’s operation.

• The operation is create and the person’s wallet was deleted, so their identity value cannot be reused.

Failed rows are reported in the destination’s run details. A row whose wallet is saved but whose additional identity, scheme account, or state change Eagle Eye rejects counts as succeeded, and the reason is listed in the error log for the run. See Additional identities and loyalty schemes.

Some conditions stop the entire run instead of failing individual rows: query results with no identity_value column (or no friendly_name column when the operation is update), query results missing an identity_value_<type> or scheme_state_<id> column for a type or scheme listed in the settings when the operation is create, an Additional identity types setting that repeats the Identity type, an unknown wallet operation, or a state-change send with no Wallet state set (all caught before any data is sent), and a rejected credential or Eagle Eye being unavailable. Campaigns report a missing column, or an Additional identity types setting that repeats the Identity type, while you edit the campaign.