Linked Accounts
Manage a Customer's Linked Accounts.
Last updated
Manage a Customer's Linked Accounts.
Last updated
One of your 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 endpoint for Rosie, the imin:item
item for Acme Leisure Centre will include:
"imin:matchingEmailExists": false
potentialAction
, containing a RegisterAction
and a CreateAction
. 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 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 a RegisterAction
and a CreateAction
. 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 endpoint for Rosie, the imin:item
item for Acme Leisure Centre will NOT include imin:matchingEmailExists
and potentialAction
, but instead includes a number of fields containing information about the Linked Account including , an Access Pass, etc.
For a full list of fields, check out the example response in .
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
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.
customerIdentifier
string
Customer Identifier
redirectUri
string
Used to create the RegisterAction
and RegisterOrCreateAction
URLs. Use the URL that you want imin to redirect to when a user has linked their account.
The RegisterAction
and RegisterOrCreateAction
will only be created if this parameter is included.
X-Api-Key
string
API Key
Key fields in the response:
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 that RegisterOrCreateAction
also includes an option to login to an existing account.
If a customer logs in to their existing account via RegisterOrCreateAction
, and the connected account does not exactly match the imin Customer Account, a CustomerUpdateAction
will be visible in imin:updateNotifications
.
imin:matchingEmailExists
: If true
, 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 Seller
imin:dateLinked
: The date the account was linked
hasHiddenEntitlements
: Whether the account has other entitlements in addition to any assigned entitlements.
CustomerUpdateAction
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
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 outstanding UnblockAction
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
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.
customerIdentifier
string
Customer Identifier
linkedAccountIdentifier
string
Linked Account Identifier
notificationIdentifier
string
Notification Identifier
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.
customerIdentifier
string
Customer Identifier
seller
string
Seller ID e.g. https://id.bookingsystem.example.com/organizers/1
X-Api-Key
string
API Key
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.
jwt
string
An opaque token created by imin
imin:entitlementFilter
: Use for .
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 ).
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 using its
.
This may include one of each:@id
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 and so you will see any errors in the response from that call.