Linked Accounts
Manage a Customer's Linked Accounts.
One of your Customers can be linked to accounts across multiple Sellers. e.g., say there is a Seller, Acme Leisure Centre. It will have its own database of Customers (or it may call them "Accounts", "Members", etc).
If a Customer has an account with a Seller that is linked to their account in your broker, the account with the Seller is called a Linked Account.
Say that you have a Customer called Rosie. There are a few different scenarios for whether or not she has a linked account with Acme Leisure Centre:
Rosie has no account with Acme Leisure Centre Rosie has no account with Acme Leisure Centre and may want to create one and link it to her account with your Broker. When calling the Get Linked Accounts endpoint for Rosie, the
imin:item
item for Acme Leisure Centre will include:"imin:matchingEmailExists": false
potentialAction
, containing aRegisterAction
and aCreateAction
. If Rosie chooses to link to an existing account in Acme Leisure Centre or create a new one, she should be redirected to either of these URLs respectively.
Rosie has an account with Acme Leisure Centre, but it is not linked Rosie does have an account with Acme Leisure Centre and may want to link this to her account with your Broker. When calling the Get Linked Accounts endpoint for Rosie, the
imin:item
item for Acme Leisure Centre will include:"imin:matchingEmailExists": true
, indicating that her email is known in this Seller and therefore will likely just have to login and link it to her account with your Broker.potentialAction
, containing aRegisterAction
and aCreateAction
. If Rosie chooses to link to an existing account in Acme Leisure Centre or create a new one, she should be redirected to either of these URLs respectively.
Rosie has a linked account with Acme Leisure Centre Rosie has already linked her Acme Leisure Centre account with her account in your broker. When calling the Get Linked Accounts endpoint for Rosie, the
imin:item
item for Acme Leisure Centre will NOT includeimin:matchingEmailExists
andpotentialAction
, but instead includes a number of fields containing information about the Linked Account including Entitlements, an Access Pass, etc. For a full list of fields, check out the example response in Get Linked Accounts.
All requests that require the X-Api-Key
header must be made Server-side. Otherwise, it would be possible to view the secret API key with a browser.
Get Linked Accounts
GET
https://book.imin.co/api/v2/customer-accounts/:customerIdentifier/linked-accounts
For a given Customer, this endpoint returns information about whether that Customer has an account with each Seller.
The response includes information about all Sellers, regardless of whether the Customer has linked to an account with that Sellers.
If an account has not been linked for a particular Seller, information will be included which will allow the Customer to do so (in the potentialAction
).
If an account has been linked for a particular Seller, information about this account will be included in the response.
Key fields in the response:
• imin:item[].potentialAction[].target
: Direct a Customer to this URL in order to have them login/register with the Seller and link their account to your Broker. This URL is for the Connect Account endpoint.
Path Parameters
Query Parameters
Headers
Key fields in the response:
imin:entitlementFilter
: Use for Entitlement Pricing in Search.
If there is no Linked Account
potentialAction
: URLs that you can have your customer navigate to in order to either log in to an existing account with the Seller (RegisterAction
) or create a new one (RegisterOrCreateAction
). Note thatRegisterOrCreateAction
also includes an option to login to an existing account.If a new account is created by
RegisterOrCreateAction
, it is automatically updated with the current details within the imin Customer Account (that were previously added via Update Customer Account).If a customer logs in to their existing account via
RegisterOrCreateAction
, and the connected account does not exactly match the imin Customer Account, aCustomerUpdateAction
will be visible inimin:updateNotifications
.
imin:matchingEmailExists
: Iftrue
, there is an account with the same email with the Seller.
If there is a Linked Account
accountNumber
: The membership number of the Customer with this Sellerimin:dateLinked
: The date the account was linkedhasHiddenEntitlements
: Whether the account has other entitlements in addition to any assigned entitlements.imin:updateNotifications
: Notifications that a change has happened to the Customer's details or Barcode in this Linked Account. You may, upon seeing this, wish to notify your Customer about the change. Verify that you or your Customer have processed the notification by calling Delete Notification using its
. This may include one of each:@idCustomerUpdateAction
imin:AccessPassUpdateAction
Note that an
imin:EntitlementUpdateAction
will not be shown here as exact Linked Account Entitlements are not visible in the API. User experience note: You should check for notifications before allowing the user to update their customer details or before setting a barcode, in case there is an update notification pending from a linked account. For example, if a user is about to edit their customer details, then they probably would be interested to see that the update from a linked account is pending (if they just made the same update there).imin:updateFailures
: Any errors that were received while attempting to update account details in the Linked Account. This may include one of each:imin:AccessPassUpdateAction
imin:EntitlementUpdateAction
Note that a
CustomerUpdateAction
will not be shown here as these actions are never asserted onto Linked Accounts in the background - they are only asserted by your making a call to Update Customer Account and so you will see any errors in the response from that call.outstandingAction
: Any outstanding actions on this Customer Account, such as the resolution of outstanding debts or membership renewal. These may prevent the Customer from making bookings until resolved.UnblockAction
is reserved for actions that are required to make any booking (e.g. paying outstanding debts) User experience note: Any outstandingUnblockAction
entries should be displayed prominently, as they will prevent the Customer from making any bookings if not resolved.ResolveAction
is reserved for actions that are required to make specific bookings, or which are generally useful for the upkeep of the account (e.g. attending an in-person gym induction, or viewing an online gym induction).
Delete Notification
DELETE
https://book.imin.co/api/v2/customer-accounts/:customerIdentifier/linked-accounts/:linkedAccountIdentifier/linked-account-updates/:notificationIdentifier
This URL to use for the DELETE call will be found in the imin:updateNotifications
field in the response from Get Linked Accounts.
Path Parameters
Delete Linked Account
DELETE
https://book.imin.co/api/v2/customer-accounts/:customerIdentifier/linked-accounts
Unlink the Customer's account within a specified Seller from the Customer's account within your Broker.
Path Parameters
Query Parameters
Headers
Connect Account
GET
https://book.imin.co/auth/connect-account
Note: Do not navigate manually to this endpoint. URLs for accessing this endpoint will be generated in the potentialAction
target URLs found in the response from the Get Linked Account endpoint.
When a Customer navigates to this page, the process for connecting with a Linked Account will initiate.
Query Parameters
Last updated