{
  "openapi": "3.0.0",
  "info": {
    "title": "Entry Point API",
    "description": "Add links or buttons to your App which take customers into a hosted web view to allow them to refer their friends or become referred.",
    "termsOfService": "https://mention-me.com/help/tnc_f/site",
    "version": "v2"
  },
  "servers": [
    {
      "url": "https://mention-me.com",
      "description": "Production"
    },
    {
      "url": "https://demo.mention-me.com",
      "description": "Demo"
    }
  ],
  "paths": {
    "/api/entry-point/{version}/offer": {
      "post": {
        "tags": [
          "Referrer"
        ],
        "summary": "Enrol a customer in an offer",
        "description": "Provide a customers' details so we can tell you if we could enrol them into an offer. We'll provide the URL to the web-view for their journey.\n\nGiven a set of input parameters about the customer (and segment and any order that has just taken place), decide if we could enrol them as a customer and if so, give you a link to the web view so they can share the offer - whether referral, IFA or NPS - with their friends.\n\nWe encourage you to include the details of any order which has just taken place as this helps us with segmentation and propensity modelling. You can tell us about orders separately too.\n\nYou can present this as a button, link or broader display panel. We include other useful content which you can choose to present to the customer to give them a richer invitation to join the promotion\nprogramme. A headline and description describe the offer and the default CTA text gives you content to add to the link or button. There is also an optional image URL. There is also an optional privacy information notice if you need it.\n\nUsers of the Mention Me platform can configure and edit the content and image returned and those can be AB tested also - for example half the customers see one image and one set of content and half see another so that you can test how offers perform.\n\nNote: you can also use `/api/entry-point/{version}/referrer` as the endpoint, which is an alias of this path",
        "operationId": "post_api_entry_point_offer",
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "description": "Version",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "v2|v1",
              "enum": [
                "v2",
                "v1"
              ]
            },
            "example": "v2"
          }
        ],
        "requestBody": {
          "description": "Information to retrieve an offer entry point URL",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EntryPointForReferrerType"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returned when successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntryPointOfferAndLink"
                }
              }
            }
          },
          "404": {
            "description": "Returned when this specific integration point has been disabled"
          },
          "422": {
            "description": "The data presented contains validation errors, please correct and try again"
          },
          "500": {
            "description": "Internal server error, unable to complete the request"
          }
        }
      }
    },
    "/api/entry-point/{version}/referee": {
      "post": {
        "tags": [
          "Referee"
        ],
        "summary": "Find a friend by name",
        "description": "Provide some details of a referee (optional - if you have them) and some context (such as locale) so we can tell you if we can serve a name finder journey. We'll provide the URL to the web-view for their journey.\n\nGiven a set of input parameters about the referee (and segment etc), decide if we could serve them a referee\nname finder journey and give them a link to the web view for doing that.\n\nIf you choose to direct the consumer to the URL via an iframe, the closing of the journey and the fulfillment of any coupon is done via postMessage. If you send the consumer to the URL they will close the flow using the browser itself and the CTA at the end is the defined CTA URL to take them to the next step of their journey.",
        "operationId": "post_api_entry_point_referee",
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "description": "Version",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "v2|v1",
              "enum": [
                "v2",
                "v1"
              ]
            },
            "example": "v2"
          }
        ],
        "requestBody": {
          "description": "Information to retrieve a referee entry point URL",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EntryPointForRefereeType"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returned when successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntryPointLink"
                }
              }
            }
          },
          "404": {
            "description": "Returned when this specific integration point has been disabled"
          },
          "422": {
            "description": "Data had validation errors"
          },
          "500": {
            "description": "Internal server error, unable to complete the request"
          }
        }
      }
    },
    "/api/entry-point/{version}/dashboard": {
      "post": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Get dashboard",
        "description": "Provide a customers' details so we can tell you if we could show them a dashboard (or offer). We'll provide the URL to the web-view for their dashboard.\n\nProvide their full details (name, email, customerId) if you want us to optionally register them if they're not yet a referrer.\n\nFor information on how to correctly generate the Authentication Token, please see the documentation: https://docs.mention-me.com/api-reference/entry-point-api/authentication-token",
        "operationId": "post_api_entry_point_dashboard",
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "description": "Version",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "v2|v1",
              "enum": [
                "v2",
                "v1"
              ]
            },
            "example": "v2"
          }
        ],
        "requestBody": {
          "description": "Information to retrieve a referrer dashboard entry point URL",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EntryPointForDashboardType"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returned when successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntryPointLink"
                }
              }
            }
          },
          "404": {
            "description": "Returned when this specific integration point has been disabled, or we are unable to serve a dashboard for this customer"
          },
          "422": {
            "description": "The data presented contains validation errors, please correct and try again"
          },
          "500": {
            "description": "Internal server error, unable to complete the request"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RequestAuthentication": {
        "required": [
          "partnerCode",
          "situation",
          "authenticationToken",
          "localeCode"
        ],
        "properties": {
          "partnerCode": {
            "description": "Your partner code, used to link to your users and offers",
            "type": "string",
            "example": "[YOUR-PARTNER-CODE]"
          },
          "situation": {
            "description": "Situation - a string representing where in the application you are making this request",
            "type": "string",
            "example": "mobile-app"
          },
          "segment": {
            "description": "Segment - the segment the customer belongs to",
            "type": "string",
            "example": "vip"
          },
          "localeCode": {
            "description": "Locale code - ISO standard locale code (e.g. en_GB) for the locale you expect the content to be in",
            "type": "string",
            "example": "en_GB"
          },
          "ipAddress": {
            "description": "IP address of the customer connection. If you're making a request on behalf of a customer, pass their IP address here. If the customer will connect directly, leave this empty and we will retrieve this from their request.",
            "type": "string",
            "example": "127.0.0.1"
          },
          "userDeviceIdentifier": {
            "description": "User Device Identifier should be a unique reference to this device. We use this for preventing gaming. Multiple users with the same Device Identifier will be treated as the same individual and may be flagged for gaming. On Android the UniqueID could be an InstanceID or GUID. On iPhone the UniqueID should be generated by identifierForVendor.",
            "type": "string",
            "example": ""
          },
          "deviceType": {
            "description": "Device type - your description of the device the user is using. We use this for performance and conversion optimisation.",
            "type": "string",
            "example": ""
          },
          "appName": {
            "description": "Your application name. Used for reporting.",
            "type": "string",
            "example": ""
          },
          "appVersion": {
            "description": "Your application version reference. Used for reporting and troubleshooting.",
            "type": "string",
            "example": "e.g. MyApp/v1.73"
          },
          "authenticationToken": {
            "description": "This is a signature using a salted hash of the email address of the customer with a secret key, and validates the authenticity of the request.\n\nFor information on how to correctly generate this token, please see the documentation: https://docs.mention-me.com/api-reference/entry-point-api/authentication-token",
            "type": "string",
            "example": ""
          }
        },
        "type": "object"
      },
      "Referee": {
        "properties": {
          "emailAddress": {
            "description": "Customer email address",
            "type": "string",
            "example": ""
          },
          "title": {
            "description": "Customer title such as Mr, Miss, Dr or Sir",
            "type": "string",
            "example": ""
          },
          "firstname": {
            "description": "Customer firstname",
            "type": "string",
            "example": ""
          },
          "surname": {
            "description": "Customer surname",
            "type": "string",
            "example": ""
          },
          "uniqueIdentifier": {
            "description": "Your unique identifier for this customer e.g. CustomerId",
            "type": "string",
            "example": ""
          }
        },
        "type": "object"
      },
      "RequestWithVariation": {
        "required": [
          "partnerCode",
          "situation",
          "localeCode"
        ],
        "properties": {
          "partnerCode": {
            "description": "Your partner code, used to link to your users and offers",
            "type": "string",
            "example": "[YOUR-PARTNER-CODE]"
          },
          "situation": {
            "description": "Situation - a string representing where in the application you are making this request",
            "type": "string",
            "example": "mobile-app"
          },
          "segment": {
            "description": "Segment - the segment the customer belongs to",
            "type": "string",
            "example": "vip"
          },
          "localeCode": {
            "description": "Locale code - ISO standard locale code (e.g. en_GB) for the locale you expect the content to be in",
            "type": "string",
            "example": "en_GB"
          },
          "ipAddress": {
            "description": "IP address of the customer connection. If you're making a request on behalf of a customer, pass their IP address here. If the customer will connect directly, leave this empty and we will retrieve this from their request.",
            "type": "string",
            "example": "127.0.0.1"
          },
          "userDeviceIdentifier": {
            "description": "User Device Identifier should be a unique reference to this device. We use this for preventing gaming. Multiple users with the same Device Identifier will be treated as the same individual and may be flagged for gaming. On Android the UniqueID could be an InstanceID or GUID. On iPhone the UniqueID should be generated by identifierForVendor.",
            "type": "string",
            "example": ""
          },
          "deviceType": {
            "description": "Device type - your description of the device the user is using. We use this for performance and conversion optimisation.",
            "type": "string",
            "example": ""
          },
          "appName": {
            "description": "Your application name. Used for reporting.",
            "type": "string",
            "example": ""
          },
          "appVersion": {
            "description": "Your application version reference. Used for reporting and troubleshooting.",
            "type": "string",
            "example": "e.g. MyApp/v1.73"
          },
          "variation": {
            "description": "Variation - an index (0,1,2...) specifying which of the currently running AB tests to choose (if available)",
            "type": "string",
            "example": ""
          }
        },
        "type": "object"
      },
      "Request": {
        "required": [
          "partnerCode",
          "situation",
          "localeCode"
        ],
        "properties": {
          "partnerCode": {
            "description": "Your partner code, used to link to your users and offers",
            "type": "string",
            "example": "[YOUR-PARTNER-CODE]"
          },
          "situation": {
            "description": "Situation - a string representing where in the application you are making this request",
            "type": "string",
            "example": "mobile-app"
          },
          "segment": {
            "description": "Segment - the segment the customer belongs to",
            "type": "string",
            "example": "vip"
          },
          "localeCode": {
            "description": "Locale code - ISO standard locale code (e.g. en_GB) for the locale you expect the content to be in",
            "type": "string",
            "example": "en_GB"
          },
          "ipAddress": {
            "description": "IP address of the customer connection. If you're making a request on behalf of a customer, pass their IP address here. If the customer will connect directly, leave this empty and we will retrieve this from their request.",
            "type": "string",
            "example": "127.0.0.1"
          },
          "userDeviceIdentifier": {
            "description": "User Device Identifier should be a unique reference to this device. We use this for preventing gaming. Multiple users with the same Device Identifier will be treated as the same individual and may be flagged for gaming. On Android the UniqueID could be an InstanceID or GUID. On iPhone the UniqueID should be generated by identifierForVendor.",
            "type": "string",
            "example": ""
          },
          "deviceType": {
            "description": "Device type - your description of the device the user is using. We use this for performance and conversion optimisation.",
            "type": "string",
            "example": ""
          },
          "appName": {
            "description": "Your application name. Used for reporting.",
            "type": "string",
            "example": ""
          },
          "appVersion": {
            "description": "Your application version reference. Used for reporting and troubleshooting.",
            "type": "string",
            "example": "e.g. MyApp/v1.73"
          }
        },
        "type": "object"
      },
      "OrderDetails": {
        "required": [
          "orderIdentifier",
          "total",
          "currencyCode",
          "dateString"
        ],
        "properties": {
          "orderIdentifier": {
            "description": "Your Order Identifier for the transaction that has taken place",
            "type": "string",
            "example": "123456"
          },
          "total": {
            "description": "Order subtotal, excluding tax and shipping in the currency specified by currencyCode",
            "type": "string",
            "example": "100"
          },
          "currencyCode": {
            "description": "3 letter currency code for the currency in which the transaction took place. Use the ISO4217 format (e.g. GBP, EUR, etc",
            "type": "string",
            "example": "GBP"
          },
          "dateString": {
            "description": "The date on which the transaction took place (typically the current date/time). Use ISO8601 format (e.g. 2016-11-30T17:52:50Z)",
            "type": "string",
            "example": "2026-01-01T12:00:00+00:00"
          },
          "couponCode": {
            "description": "If a coupon was used in the transaction, the coupon code the consumer used. If multiple coupons were used, pass them as a comma separated list. Leave blank if no coupon was used.",
            "type": "string",
            "example": "ABC23252"
          },
          "discountAmount": {
            "description": "The discount amount. Our assumption is this has already been taken off the order subtotal provided. This allows us to calculate the Cost Per Acquisition for referral.",
            "type": "string",
            "example": "12.44"
          },
          "orderItemCount": {
            "description": "The number of items in the order/cart (if applicable). This helps us understand the type of purchase and can be a signal of advocacy.",
            "type": "string",
            "example": "3"
          },
          "isSubscription": {
            "description": "Whether this order is for a subscription (recurring). This helps us qualify and categorise the revenue.",
            "type": "boolean",
            "example": ""
          },
          "isGift": {
            "description": "Whether this order is a gift (being bought for someone else). Gifts can be signals of advocacy.",
            "type": "boolean",
            "example": ""
          }
        },
        "type": "object"
      },
      "ImplementationDetails": {
        "properties": {
          "wrapContentWithBranding": {
            "description": "If true (default), serve content in the URLs with customisable branding wrapper (normally a logo and padding). If false, serve content without any wrapping. ",
            "type": "boolean",
            "example": true
          },
          "showCloseIcon": {
            "description": "If true (and the page is rendered inside an iframe), Mention Me will include a close icon. A user clicking on the close icon will trigger a postMessage event which can be listened to for closing the iframe. Documentation is available at https://docs.mention-me.com/developer-docs/advanced/postmessage-iframe",
            "type": "boolean",
            "example": false
          }
        },
        "type": "object"
      },
      "CustomerEnrolling": {
        "required": [
          "emailAddress",
          "firstname",
          "surname"
        ],
        "properties": {
          "emailAddress": {
            "description": "Customer email address",
            "type": "string",
            "example": "jane.doe@example.com"
          },
          "title": {
            "description": "Customer title such as Mr, Miss, Dr or Sir",
            "type": "string",
            "example": ""
          },
          "firstname": {
            "description": "Customer firstname",
            "type": "string",
            "example": ""
          },
          "surname": {
            "description": "Customer surname",
            "type": "string",
            "example": ""
          },
          "uniqueIdentifier": {
            "description": "Your unique identifier for this customer e.g. CustomerId",
            "type": "string",
            "example": ""
          },
          "segment": {
            "description": "Customer segment - a string containing segment data about this customer, e.g. vip or employee. You can concatenate multiple segments together if you wish using hyphens.",
            "type": "string",
            "example": ""
          },
          "customField": {
            "description": "Custom field - a string containing custom data about this customer, e.g. SEGMENT001 or Package B",
            "type": "string",
            "example": ""
          },
          "visitorId": {
            "description": "The visitor ID from the MentionMe Browser Fingerprint, used to link customer journeys. This should be a SHA256 hash (browserId + clientIP).",
            "type": "string",
            "example": ""
          },
          "hasEngaged": {
            "description": "Has this customer been informed of their privacy rights, and actively engaged in the offer? Mention Me expects you to set this as false when you first show the offer, and true when someone has actively engaged, e.g. after clicking a call to action. If no value is provided, we will use the default defined on the offer.",
            "type": "boolean",
            "example": false
          }
        },
        "type": "object"
      },
      "CustomerDetails": {
        "required": [
          "emailAddress",
          "firstname",
          "surname"
        ],
        "properties": {
          "emailAddress": {
            "description": "Customer email address",
            "type": "string",
            "example": "jane.doe@example.com"
          },
          "title": {
            "description": "Customer title such as Mr, Miss, Dr or Sir",
            "type": "string",
            "example": ""
          },
          "firstname": {
            "description": "Customer firstname",
            "type": "string",
            "example": ""
          },
          "surname": {
            "description": "Customer surname",
            "type": "string",
            "example": ""
          },
          "uniqueIdentifier": {
            "description": "Your unique identifier for this customer e.g. CustomerId",
            "type": "string",
            "example": ""
          },
          "segment": {
            "description": "Customer segment - a string containing segment data about this customer, e.g. vip or employee. You can concatenate multiple segments together if you wish using hyphens.",
            "type": "string",
            "example": ""
          },
          "customField": {
            "description": "Custom field - a string containing custom data about this customer, e.g. SEGMENT001 or Package B",
            "type": "string",
            "example": ""
          },
          "visitorId": {
            "description": "The visitor ID from the MentionMe Browser Fingerprint, used to link customer journeys. This should be a SHA256 hash (browserId + clientIP).",
            "type": "string",
            "example": ""
          }
        },
        "type": "object"
      },
      "Address": {
        "properties": {
          "addressLine1": {
            "description": "First line of address",
            "type": "string",
            "example": ""
          },
          "addressLine2": {
            "description": "Second line of address",
            "type": "string",
            "example": ""
          },
          "addressCity": {
            "description": "City part of address",
            "type": "string",
            "example": ""
          },
          "addressCounty": {
            "description": "County or state part of address",
            "type": "string",
            "example": ""
          },
          "addressPostCode": {
            "description": "Post or ZIP code",
            "type": "string",
            "example": ""
          },
          "addressCountry": {
            "description": "Country of address",
            "type": "string",
            "example": ""
          }
        },
        "type": "object"
      },
      "AddressWithCountry": {
        "properties": {
          "addressCountry": {
            "description": "Country of address e.g. UK or France",
            "type": "string",
            "example": ""
          }
        },
        "type": "object"
      },
      "EntryPointForReferrerType": {
        "required": [
          "customer",
          "request"
        ],
        "properties": {
          "customer": {
            "title": "Customer",
            "description": "Information about the referrer",
            "oneOf": [
              {
                "$ref": "#/components/schemas/CustomerDetails"
              }
            ]
          },
          "request": {
            "title": "Request",
            "description": "Information about the request",
            "oneOf": [
              {
                "$ref": "#/components/schemas/RequestWithVariation"
              }
            ]
          },
          "order": {
            "title": "Order",
            "description": "Information about the order (used for recording order events AND segmentation)",
            "oneOf": [
              {
                "$ref": "#/components/schemas/OrderDetails"
              }
            ]
          },
          "address": {
            "title": "Address",
            "description": "Information about the address of the customer",
            "oneOf": [
              {
                "$ref": "#/components/schemas/Address"
              }
            ]
          },
          "implementation": {
            "title": "Implementation",
            "description": "Options for the implementation",
            "oneOf": [
              {
                "$ref": "#/components/schemas/ImplementationDetails"
              }
            ]
          }
        },
        "type": "object"
      },
      "EntryPointOfferAndLink": {
        "properties": {
          "url": {
            "title": "The url to include in the share",
            "type": "string"
          },
          "defaultCallToAction": {
            "title": "The default message to include as the CTA",
            "type": "string",
            "default": ""
          },
          "localeCode": {
            "title": "The locale code of the Offer - the locale in which the content is presented",
            "type": "string"
          },
          "headline": {
            "title": "The headline description for the Offer.",
            "description": "e.g. \"You can get a £20 gift card if you refer a friend to ...\"",
            "type": "string"
          },
          "description": {
            "title": "The details of the Offer.",
            "description": "e.g. \"Give your friends a 20% off introductory offer\"",
            "type": "string"
          },
          "privacyNotice": {
            "title": "The privacyNotice text of the Offer - typically shown near the CTA if required by privacy regulation",
            "description": "e.g. \"Our refer-a-friend programme is managed by Mention Me who will process your data and send you referral service emails.\"",
            "type": "string"
          },
          "privacyNoticeUrl": {
            "title": "The Mention Me privacy policy URL.",
            "type": "string"
          },
          "privacyNoticeLinkText": {
            "title": "The text to use for linking to $privacyNoticeUrl.",
            "type": "string"
          },
          "imageUrl": {
            "title": "The URL to an image for the Offer.",
            "type": "string"
          },
          "offerCode": {
            "title": "The code which identifies the offer we picked (which could be used for the client to style the placement differently). It is the QuickLinkCode of the Offer.",
            "type": "string"
          },
          "termsAndConditionsUrl": {
            "title": "The terms and conditions link for the Offer.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "EntryPointForRefereeType": {
        "required": [
          "request"
        ],
        "properties": {
          "customer": {
            "title": "Referee",
            "description": "Information about the referee (if you have any)",
            "oneOf": [
              {
                "$ref": "#/components/schemas/Referee"
              }
            ]
          },
          "request": {
            "title": "Request",
            "description": "Information about the request",
            "oneOf": [
              {
                "$ref": "#/components/schemas/RequestWithVariation"
              }
            ]
          },
          "implementation": {
            "title": "Implementation",
            "description": "Options for the implementation",
            "oneOf": [
              {
                "$ref": "#/components/schemas/ImplementationDetails"
              }
            ]
          }
        },
        "type": "object"
      },
      "EntryPointLink": {
        "properties": {
          "url": {
            "title": "The url to include in the share",
            "type": "string"
          },
          "defaultCallToAction": {
            "title": "The default message to include as the CTA",
            "type": "string",
            "default": ""
          }
        },
        "type": "object"
      },
      "EntryPointForDashboardType": {
        "required": [
          "customer",
          "request"
        ],
        "properties": {
          "customer": {
            "title": "Customer",
            "description": "Information about the referrer",
            "oneOf": [
              {
                "$ref": "#/components/schemas/CustomerDetails"
              }
            ]
          },
          "request": {
            "title": "Request",
            "description": "Information about the request, including authentication",
            "oneOf": [
              {
                "$ref": "#/components/schemas/RequestAuthentication"
              }
            ]
          }
        },
        "type": "object"
      }
    }
  },
  "tags": [
    {
      "name": "Referrer"
    },
    {
      "name": "Referee"
    },
    {
      "name": "Dashboard"
    }
  ]
}