Seller Accounts \[BETA\]

One of your Customers can be connected to multiple Seller accounts. 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).

Say that you have a Customer called Rosie. There are a few different scenarios for whether or not she has a connected 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 connect it to her account with your Broker. When calling the Get Seller 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 connect 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 unconnected

Rosie does have an account with Acme Leisure Centre and may want to connect this to her account with your Broker.

When calling the Get Seller 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 connect it to her account with your Broker.
- potentialAction, containing a RegisterAction and a CreateAction. If Rosie chooses to connect 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 connected acount with Acme Leisure Centre Rosie has already connected her Acme Leisure Centre account with her account in your broker. When calling the Get Seller 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 Seller account including Entitlements, an Access Pass, etc. For a full list of fields, check out the example response in Get Seller Accounts.

Get Seller Accounts

GET https://book.imin.co/api/v2/customers/:customerIdentifier/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 Booking Systems, regardless of whether the Customer has connected to an account with that Booking System.

If an account has not been connected for a particular Seller, information will be included which will allow the Customer to do so (in the potentialAction).

If an account has been connected 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 connect their account to your Broker. This URL is for the Connect Account endpoint.

Path parameters

Name	Type	Required	Description
`customerIdentifier`	`string`	yes	Customer Identifier

Headers

Name	Type	Required	Description
`X-Api-Key`	`string`	yes	API Key

Query parameters

Name	Type	Required	Description
`redirectUri`	`string`	no	Used to create the RegisterAction and CreateAction URLs. Use the URL that you want imin to redirect to when a user has connected their account. The RegisterAction and CreateActions will only be created if this param is included.

Response 200

{
  "@context": [
    "https://openactive.io/",
    "https://schema.imin.co/"
  ],
  "@id": "https://book.imin.co/api/v2/customers/1234/accounts",
  "@type": "imin:Collection",
  "imin:entitlementFilter": "<opaque token>",
  "imin:item": [{
    "@type": "Account",
    "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": "contact@acmeleisurecentre.com",
      "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": "CreateAction",
        "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 👇👇👇
    "dateLinked": "2021-01-27T12:00:00Z",
    "hiddenEntitlements": true,
    "customer": {
      "@type": "Person",
      "email": "<email address>",
      "dateModified": "2021-01-27T12:00:00Z"
    },
    "accessPass": {
      "@type": "Barcode",
      "text": "<barcode number>",
      "dateModified": "2021-01-27T12:00:00Z"
    },
    "imin:entitlementUpdateErrors": [{
      "@context": "https://openactive.io/",
      "@type": "EntitlementConflict",
      "name": "The entitlement cannot be applied due to other entitlements already associated with the Customer.",
      "description": "This customer already has a paid monthly membership",
    }],
    "imin:evidenceRequests": [{
      "@context": "https://openactive.io/",
      "@type": "Entitlement",
      "@id": "https://id.example.com/entitlements/1234",
      "expires": "2021-05-10T10:45:33+00:00",
      "evidenceRequest": {
        "@type": "EvidenceRequestAction",
        "url": "https://legend.example.com/upload-form/1234/magic-link/abc",
        "expiry": "2021-07-10T10:45:33+00:00",
        "actionStatus": "https://schema.org/CompletedActionStatus"
      },
      "entitlementType": {
        "@type": "Concept",
        "@id": "https://gll.example.com/openactive/entitlement-list#5e78bcbe-36db-425a-9064-bf96d09cc351",
        "prefLabel": "MCRactive Adult Resident",
        "inScheme": "https://gll.example.com/openactive/entitlement-list"
      }
    }]
    // 👆👆👆 These fields are only included if this account IS connected with this customer 👆👆👆
  }]
}

The imin:entitlementFilter value, from the response, can be used in Search so that the Customer is shown Entitlement Pricing: Entitlement Filter (Search) [BETA].

Delete Seller Account

DELETE https://book.imin.co/api/v2/customers/:customerIdentifier/accounts

Disconnect the Customer’s account within a specified Seller from the Customer’s account within your Broker.

Path parameters

Name	Type	Required	Description
`customerIdentifier`	`string`	yes	Customer Identifier

Headers

Name	Type	Required	Description
`X-Api-Key`	`string`	yes	API Key

Query parameters

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

Response 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 Seller Account endpoint.

When a Customer navigates to this page, the process for connecting with a Seller Account will initiate.

Query parameters

Name	Type	Required	Description
`jwt`	`string`	yes	An opaque token created by imin

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