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:

1. 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 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.

2. 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 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.

3. 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 include imin:matchingEmailExists and potentialAction, 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

Name	Type	Description
customerIdentifier	string	Customer Identifier

Query Parameters

Name	Type	Description
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.

Headers

Name	Type	Description
X-Api-Key	string	API Key

200

{
  "@context": [
    "https://openactive.io/",
    "https://schema.imin.co/"
  ],
  "@id": "https://book.imin.co/api/v2/customer-accounts/1234/linked-accounts",
  "@type": "imin:Collection",
  "imin:entitlementFilter": "<opaque token>",
  "imin:item": [{
    "@type": "CustomerAccount",
    "@id": "https://example-linked-booking-system.com/customer-accounts/fdc14503-275e-46d3-9922-45b986c9f9aa",
    "accountNumber": "CA00000123",
    "seller": {
      "@type": "Organization",
      "@id": "https://id.bookingsystem.example.com/organizers/1",
      "name": "Acme Leisure Centre",
      "url": "https://acmeleisurecentre.com/",
      "logo": {
        "@type": "ImageObject",
        "url": "https://acmeleisurecentre.com/logo.jpg"
      },
      "email": "[e-mail]",
      "telephone": "01455 890508",
      "sameAs": [
        "https://www.facebook.com/acmeleisurecentre/",
        "https://twitter.com/acmeleisurecentre"
      ]
    },

    // 👇👇👇 These fields are only included if this account is NOT connected with this customer 👇👇👇
    "potentialAction": [
      {
        "@type": "RegisterAction",
        "target": "https://book.imin.co/auth/connect-account?jwt=<opaque token>"
      },
      {
        "@type": "RegisterOrCreateAction",
        "target": "https://book.imin.co/auth/connect-account?jwt=<opaque token>"
      }
    ],
    "imin:matchingEmailExists": true,
    // 👆👆👆 These fields are only included if this account is NOT connected with this customer 👆👆👆

    // 👇👇👇 These fields are only included if this account IS connected with this customer 👇👇👇
    "imin:dateLinked": "2021-01-27T12:00:00Z",
    "hasHiddenEntitlements": true,
    "customer": {
      "@type": "Person",
      "email": "<email address>"
    },
    "accessPass": {
      "@type": "Barcode",
      "text": "<barcode number>"
    },
    "imin:updateNotifications": [
      {
        "@type": "CustomerUpdateAction",
        "@id": "https://book.imin.co/api/v2/customer-accounts/1234/linked-accounts/5678/linked-account-updates/JhbGciOiJIUzI1NiIsInR5cCI",
        "actionStatus": "https://schema.org/CompletedActionStatus"
      },
      {
        "@type": "imin:AccessPassUpdateAction",
        "@id": "https://book.imin.co/api/v2/customer-accounts/1234/linked-accounts/5678/linked-account-updates/iIxMjM0NTY3ODkwIiwibm",
        "actionStatus": "https://schema.org/CompletedActionStatus"
      }
    ],
    "imin:updateFailures": [
      {
        "@type": "imin:EntitlementUpdateAction",
        "actionStatus": "https://schema.org/FailedActionStatus",
        "error": [
          {
            "@context": "https://openactive.io/",
            "@type": "EntitlementConflictError",
            "name": "The entitlement cannot be applied due to other entitlements already associated with the Customer.",
            "description": "This customer already has a paid monthly membership"
          }
        ]
      },
      {
        "@type": "imin:AccessPassUpdateAction",
        "actionStatus": "https://schema.org/FailedActionStatus",
        "error": [
          {
            "@context": "https://openactive.io/",
            "@type": "BarcodeInvalidError",
            "name": "The barcode value specified is not permitted within this booking system.",
          }
        ]
      }
    ],
    "outstandingAction": [
      {
        "@type": "UnblockAction",
        "description": "There is unpaid debt on your account. You must log in to your account and pay this debt in order to continue to make bookings.",
        "target": [
          {
            "@type": "EntryPoint",
            "urlTemplate": "https://example-booking-system.com/login"
          }
        ]
      },
      {
        "@type": "UnblockAction",
        "description": "Your pay monthly membership has expired. Please log in to your example-operator.co.uk account to renew your membership.",
        "target": [
          {
            "@type": "EntryPoint",
            "urlTemplate": "https://example-booking-system.com/login"
          }
        ]
      },
      {
        "@type": "ResolveAction",
        "description": "You have not yet completed your gym induction, so you will not be able to book gym activities. Please book a gym induction."
      }
    ]
    // 👆👆👆 These fields are only included if this account IS connected with this customer 👆👆👆
  }]
}

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 that RegisterOrCreateAction 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, 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.

• 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 @id. This may include one of each:

  • 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

  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 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 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

Name	Type	Description
customerIdentifier	string	Customer Identifier
linkedAccountIdentifier	string	Linked Account Identifier
notificationIdentifier	string	Notification Identifier

204 Notification has been deleted. Next time you load up Get Linked Accounts for this Customer, you won't see the notification.

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

Name	Type	Description
customerIdentifier	string	Customer Identifier

Query Parameters

Name	Type	Description
seller	string	Seller ID e.g. https://id.bookingsystem.example.com/organizers/1

Headers

Name	Type	Description
X-Api-Key	string	API Key

204 Account has been successfully disconnected

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

Name	Type	Description
jwt	string	An opaque token created by imin

302 Customer is redirected to the Sellers's website, wherein they can login/register and consent to connecting their account with your Broker. When this is complete, the Seller will be redirected to the redirectUri specified in the call to Get Seller Account.