📌 Purpose

This API recipe enables you to seamlessly onboard customers into your loyalty program. With a single call to the services/wallet/accounts API endpoint, you can simultaneously: create a customer wallet, setup a consumer profile, add identity types, create a points account, and issue welcome offers.

This streamlined setup supports efficient registration and a strong first impression through instant points and reward availability.

🖼 Recipe Overview

This recipe will show the request of a wallet accounts services API call, allowing you to create multiple objects within a wallet at once. Once the wallet is created, the wallet can immediately start earning points and redeeming coupons once transactions are settled. By the end of this setup, you will have:

A consumer wallet created
A consumer object established
Two identity types: CUSTOMER_ID and PHONENUMBER
A loyalty points account linked to a points scheme
One or more coupon accounts, triggered by active campaigns tagged welcomeOffer

📋 Prerequisites

Eagle Eye API credentials
A configured company with 3-level unit hierarchy
schemeId for the loyalty program
Active campaign(s) tagged welcomeOffer
Unique identity values for CUSTOMER_ID and PHONENUMBER

📤 Outputs

Output Name	Purpose
walletId	Unique reference for the wallets used in multiple API calls across AIR
accountIds	Used to reference specific accounts in external platforms and in AIR API calls

📒 Steps

Step 1: Prepare the payload

1.1 Provide a value for each identity type:
- CUSTOMER_ID
- PHONENUMBER

⚠️
These must be unique within the company unit

1.2 To issue welcome coupons, set the campaignTag value to welcomeOffer under accounts.campaign

⚠️
Tags are case sensitive

1.3 Include the schemeId for the loyalty program in accounts.scheme
1.4 Add additional consumer details (e.g., birthDate, language) as needed.

Step 2: Call POST /services/wallet/accounts

{
	"state": "DEFAULT",
	"status": "ACTIVE",
	"type": "CONSUMER",
	"consumer": {
		"state": "DEFAULT",
		"status": "ACTIVE",
		"type": "INDIVIDUAL",
		"personal": {
			"language": "EN",
			"birthDate": "12-31"
		}
	},
	"identities": [
		{
			"state": "EARNBURN",
			"status": "ACTIVE",
			"type": "CUSTOMER_ID",
			"value": "custId0041"
		},
		{
			"state": "EARNBURN",
			"status": "ACTIVE",
			"type": "CARD",
			"value": "prCard0041"
		}
	],
	"accounts": {
		"scheme": [
			{
				"state": "EARNBURN",
				"status": "ACTIVE",
				"schemeId": "101161519"
			}
		]
	}
}

{
	"walletId": "241703209",
	"friendlyName": null,
	"status": "ACTIVE",
	"type": "CONSUMER",
	"state": "DEFAULT",
	"meta": [],
	"dateCreated": "2025-06-11T14:23:35+00:00",
	"lastUpdated": "2025-06-11T14:23:35+00:00",
	"relationships": {
		"parent": [],
		"child": [],
		"associate": [],
		"donor": []
	},
	"identities": [
		{
			"identityId": "193744995",
			"walletId": "241703209",
			"type": "CUSTOMER_ID",
			"friendlyName": null,
			"value": "custId0045",
			"safeValue": null,
			"secret": null,
			"dates": {
				"start": "2025-06-11T14:23:35+00:00",
				"end": null
			},
			"meta": [],
			"state": "DEFAULT",
			"status": "ACTIVE",
			"dateCreated": "2025-06-11T14:23:35+00:00",
			"lastUpdated": "2025-06-11T14:23:35+00:00",
			"mobileWallet": "https://sb.uk.mypass.is/identity/151925/241703209/193744995/18ec0892ae1e168af1a924aaa7358176cf2324e8f41ed8a6a90548064fa0f753"
		},
		{
			"identityId": "193744996",
			"walletId": "241703209",
			"type": "PHONENUMBER",
			"friendlyName": null,
			"value": "19049040045",
			"safeValue": null,
			"secret": null,
			"dates": {
				"start": "2025-06-11T14:23:35+00:00",
				"end": null
			},
			"meta": [],
			"state": "DEFAULT",
			"status": "ACTIVE",
			"dateCreated": "2025-06-11T14:23:35+00:00",
			"lastUpdated": "2025-06-11T14:23:35+00:00",
			"mobileWallet": "https://sb.uk.mypass.is/identity/151925/241703209/193744996/83f20c6baed89079fa08813bf134b62a12d6700dd843fa34de093525a05f7803"
		}
	],
	"accounts": {
		"campaign": {
			"total": 4,
			"results": [
				{
					"accountId": "4408031413",
					"walletId": "241703209",
					"campaignId": "101139352",
					"type": "ECOUPON",
					"clientType": "OFFER",
					"status": "ACTIVE",
					"state": "LOADED",
					"dates": {
						"start": "2025-06-11T14:23:35+00:00",
						"end": "2025-06-25T23:59:59+00:00"
					},
					"meta": [],
					"dateCreated": "2025-06-11T14:23:35+00:00",
					"lastUpdated": "2025-06-11T14:23:35+00:00",
					"overrides": [],
					"balances": {
						"available": 0,
						"refundable": 0
					},
					"relationships": [],
					"mobileWallet": "https://sb.uk.mypass.is/a/4408031413/120958ed1a88bbc"
				},
				{
					"accountId": "4408031414",
					"walletId": "241703209",
					"campaignId": "101139403",
					"type": "ECOUPON",
					"clientType": "OFFER",
					"status": "ACTIVE",
					"state": "LOADED",
					"dates": {
						"start": "2025-06-11T14:23:35+00:00",
						"end": "2025-06-25T23:59:59+00:00"
					},
					"meta": [],
					"dateCreated": "2025-06-11T14:23:35+00:00",
					"lastUpdated": "2025-06-11T14:23:35+00:00",
					"overrides": [],
					"balances": {
						"available": 0,
						"refundable": 0
					},
					"relationships": [],
					"mobileWallet": "https://sb.uk.mypass.is/a/4408031414/9d0857fab15c547"
				},
				{
					"accountId": "4408031415",
					"walletId": "241703209",
					"campaignId": "101139416",
					"type": "ECOUPON",
					"clientType": "OFFER",
					"status": "ACTIVE",
					"state": "LOADED",
					"dates": {
						"start": "2025-06-11T14:23:35+00:00",
						"end": "2025-06-25T23:59:59+00:00"
					},
					"meta": [],
					"dateCreated": "2025-06-11T14:23:35+00:00",
					"lastUpdated": "2025-06-11T14:23:35+00:00",
					"overrides": [],
					"balances": {
						"available": 0,
						"refundable": 0
					},
					"relationships": [],
					"mobileWallet": "https://sb.uk.mypass.is/a/4408031415/1e7bee3989da743"
				},
				{
					"accountId": "4408031416",
					"walletId": "241703209",
					"campaignId": "101141883",
					"type": "CONTINUITY",
					"clientType": "OFFER",
					"status": "ACTIVE",
					"state": "LOADED",
					"dates": {
						"start": "2025-06-11T14:23:35+00:00",
						"end": "2025-06-25T23:59:59+00:00"
					},
					"meta": [],
					"dateCreated": "2025-06-11T14:23:35+00:00",
					"lastUpdated": "2025-06-11T14:23:35+00:00",
					"overrides": [],
					"balances": {
						"totalSpend": 0,
						"currentSpend": 0,
						"transactionCount": 0,
						"currentTransactions": 0,
						"totalUnits": 0,
						"currentUnits": 0
					},
					"relationships": [],
					"mobileWallet": "https://sb.uk.mypass.is/a/4408031416/b8105e45d7e4e0c"
				}
			],
			"successful": {
				"total": 4,
				"results": [
					{
						"accountId": "4408031413",
						"walletId": "241703209",
						"campaignId": "101139352",
						"type": "ECOUPON",
						"clientType": "OFFER",
						"status": "ACTIVE",
						"state": "LOADED",
						"dates": {
							"start": "2025-06-11T14:23:35+00:00",
							"end": "2025-06-25T23:59:59+00:00"
						},
						"meta": [],
						"dateCreated": "2025-06-11T14:23:35+00:00",
						"lastUpdated": "2025-06-11T14:23:35+00:00",
						"overrides": [],
						"balances": {
							"available": 0,
							"refundable": 0
						},
						"relationships": [],
						"mobileWallet": "https://sb.uk.mypass.is/a/4408031413/120958ed1a88bbc"
					},
					{
						"accountId": "4408031414",
						"walletId": "241703209",
						"campaignId": "101139403",
						"type": "ECOUPON",
						"clientType": "OFFER",
						"status": "ACTIVE",
						"state": "LOADED",
						"dates": {
							"start": "2025-06-11T14:23:35+00:00",
							"end": "2025-06-25T23:59:59+00:00"
						},
						"meta": [],
						"dateCreated": "2025-06-11T14:23:35+00:00",
						"lastUpdated": "2025-06-11T14:23:35+00:00",
						"overrides": [],
						"balances": {
							"available": 0,
							"refundable": 0
						},
						"relationships": [],
						"mobileWallet": "https://sb.uk.mypass.is/a/4408031414/9d0857fab15c547"
					},
					{
						"accountId": "4408031415",
						"walletId": "241703209",
						"campaignId": "101139416",
						"type": "ECOUPON",
						"clientType": "OFFER",
						"status": "ACTIVE",
						"state": "LOADED",
						"dates": {
							"start": "2025-06-11T14:23:35+00:00",
							"end": "2025-06-25T23:59:59+00:00"
						},
						"meta": [],
						"dateCreated": "2025-06-11T14:23:35+00:00",
						"lastUpdated": "2025-06-11T14:23:35+00:00",
						"overrides": [],
						"balances": {
							"available": 0,
							"refundable": 0
						},
						"relationships": [],
						"mobileWallet": "https://sb.uk.mypass.is/a/4408031415/1e7bee3989da743"
					},
					{
						"accountId": "4408031416",
						"walletId": "241703209",
						"campaignId": "101141883",
						"type": "CONTINUITY",
						"clientType": "OFFER",
						"status": "ACTIVE",
						"state": "LOADED",
						"dates": {
							"start": "2025-06-11T14:23:35+00:00",
							"end": "2025-06-25T23:59:59+00:00"
						},
						"meta": [],
						"dateCreated": "2025-06-11T14:23:35+00:00",
						"lastUpdated": "2025-06-11T14:23:35+00:00",
						"overrides": [],
						"balances": {
							"totalSpend": 0,
							"currentSpend": 0,
							"transactionCount": 0,
							"currentTransactions": 0,
							"totalUnits": 0,
							"currentUnits": 0
						},
						"relationships": [],
						"mobileWallet": "https://sb.uk.mypass.is/a/4408031416/b8105e45d7e4e0c"
					}
				]
			},
			"failed": {
				"total": 0,
				"results": []
			}
		},
		"scheme": {
			"successful": {
				"results": [
					{
						"accountId": "4408031417",
						"walletId": "241703209",
						"campaignId": "100128379",
						"type": "POINTS",
						"clientType": "RETAILPOINTS",
						"status": "ACTIVE",
						"state": "EARNBURN",
						"dates": {
							"start": "2025-06-11T14:23:35+00:00",
							"end": "2038-01-19T03:14:07+00:00"
						},
						"meta": [],
						"dateCreated": "2025-06-11T14:23:35+00:00",
						"lastUpdated": "2025-06-11T14:23:35+00:00",
						"overrides": [],
						"balances": {
							"current": 0,
							"usable": 0,
							"locked": 0,
							"lifetime": 0,
							"lifetimeSpend": 0,
							"lifetimeSpendValue": 0,
							"pending": 0
						},
						"relationships": [],
						"mobileWallet": "https://sb.uk.mypass.is/a/4408031417/4cdeaa7c69ce47f"
					}
				],
				"total": 1
			},
			"failed": {
				"results": [],
				"total": 0
			},
			"total": 1,
			"results": [
				{
					"accountId": "4408031417",
					"walletId": "241703209",
					"campaignId": "100128379",
					"type": "POINTS",
					"clientType": "RETAILPOINTS",
					"status": "ACTIVE",
					"state": "EARNBURN",
					"dates": {
						"start": "2025-06-11T14:23:35+00:00",
						"end": "2038-01-19T03:14:07+00:00"
					},
					"meta": [],
					"dateCreated": "2025-06-11T14:23:35+00:00",
					"lastUpdated": "2025-06-11T14:23:35+00:00",
					"overrides": [],
					"balances": {
						"current": 0,
						"usable": 0,
						"locked": 0,
						"lifetime": 0,
						"lifetimeSpend": 0,
						"lifetimeSpendValue": 0,
						"pending": 0
					},
					"relationships": [],
					"mobileWallet": "https://sb.uk.mypass.is/a/4408031417/4cdeaa7c69ce47f"
				}
			]
		}
	},
	"consumer": {
		"consumerId": "49480048",
		"walletId": "241703209",
		"friendlyName": null,
		"type": "INDIVIDUAL",
		"state": "DEFAULT",
		"status": "ACTIVE",
		"data": [],
		"meta": [],
		"dateCreated": "2025-06-11T14:23:35+00:00",
		"lastUpdated": "2025-06-11T14:23:35+00:00"
	}
}

Repeat this step to create additional wallets, updating the identities value and consumer details for each API call.

✅ Business Readiness Checklist

Use these steps to validate the setup of your wallet and accounts:

Call GET /wallet/{walletId} to validate the response matches the values you entered in the request on step 2 of the recipe
Call GET /wallet/{walletId}/consumer to verify consumer detail
Check GET wallet/{walletId}/accounts to verify all coupon and points accounts were created

🔧 Troubleshooting Tips

Issue	Possible Cause & Resolution
Missing coupons	Double-check the campaignTag value. Tags are case sensitive. Also check for active campaigns have the appropriate tag.
207 Multi-Status response	Confirm that all referenced campaigns and schemes are active. Review your payload for the correct schemeId and campaignTag. See campaigns and schemes for more information on schemes and campaigns.