{ "openapi": "3.0.0", "info": { "title": "Consumer API", "description": "Create your own front end for the referral journey using our Consumer API.", "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/consumer/{version}/order": { "post": { "tags": [ "Record Order" ], "summary": "Record order", "description": "Tell us that an order took place.\n\nWe will use the order to:\n\n- Record the customer is an existing customer and no longer eligible for introductory rewards - Reward a referrer if this purchase was as a result of a referral\n\nWe will also use the data to optimise your referral scheme.", "operationId": "post_api_order", "parameters": [ { "name": "version", "in": "path", "description": "Version", "required": true, "schema": { "type": "string", "pattern": "v2|v1", "enum": [ "v2", "v1" ] }, "example": "v2" } ], "requestBody": { "description": "About the order", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOrderType" } } } }, "responses": { "202": { "description": "Returned when successful" }, "400": { "description": "The request contains errors" }, "403": { "description": "Returned when the integration for this merchant is not enabled" }, "404": { "description": "Returned when it is not possible to confirm an order took place with these details" }, "422": { "description": "The request cannot be processed because of validation errors" }, "500": { "description": "Internal server error, unable to complete the request" } } } }, "/api/consumer/{version}/coupon_redemption": { "post": { "tags": [ "Record Order" ], "summary": "Record order with a coupon", "description": "For In-Store situations where a referral transaction can occur identified by a coupon\nand typically without a customer email address.\n\nThe coupon must be a single-use coupon. You can validate the coupon code first using the Merchant API -> Validate Coupon Code endpoint if you wish.\n\nIf you have an email address and may not have a coupon, use the Record Order endpoint instead.\n\nWe will use the order confirmation to:\n\n- Record the customer is an existing customer and no longer eligible for introductory rewards\n(and mark their referral as redeemed)\n\n- Reward a referrer if this purchase was as a result of a referral\n\n\nWe will also use the data to optimise your referral scheme.", "operationId": "post_api_order_coupon_redemption", "parameters": [ { "name": "version", "in": "path", "description": "Version", "required": true, "schema": { "type": "string", "pattern": "v2|v1", "enum": [ "v2", "v1" ] }, "example": "v2" } ], "requestBody": { "description": "About the order", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmOrderWithCouponType" } } } }, "responses": { "202": { "description": "Returned when successful" }, "400": { "description": "The request contains errors" }, "403": { "description": "Returned when the integration for this merchant is not enabled" }, "404": { "description": "Returned when it is not possible to confirm an order took place with these details" }, "422": { "description": "The request cannot be processed because of validation errors" }, "500": { "description": "Internal server error, unable to complete the request" } } } }, "/api/consumer/{version}/referrer/enrol": { "post": { "tags": [ "Enrol Referrer" ], "summary": "Enrol referrer", "description": "Tell us about a customer (and any related order and segmentation details) to enrol them as a referrer and receive an offer to share with them", "operationId": "post_api_referrer_enrol", "parameters": [ { "name": "version", "in": "path", "description": "Version", "required": true, "schema": { "type": "string", "pattern": "v2|v1", "enum": [ "v2", "v1" ] }, "example": "v2" } ], "requestBody": { "description": "Details of the customer to enrol", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrolReferrerType" } } } }, "responses": { "200": { "description": "Returned when successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralShareOffer" } } } }, "404": { "description": "Returned when there is no suitable offer to serve this customer" }, "422": { "description": "The referrer could not be enrolled due to validation errors" }, "500": { "description": "Internal server error, unable to complete the request" } } } }, "/api/consumer/{version}/referrer/dashboard": { "get": { "tags": [ "Get referrer dashboard" ], "summary": "Get dashboard", "description": "Get a referrer's dashboard (given a referrer identity, get their dashboard data).\n\nIf we respond with a 404 they are not a referrer. Instead, you should Enrol them as a referrer first, then call this endpoint again.\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": "get_api_referrer_dashboard", "parameters": [ { "name": "version", "in": "path", "description": "Version", "required": true, "schema": { "type": "string", "pattern": "v2|v1", "enum": [ "v2", "v1" ] }, "example": "v2" }, { "name": "emailAddress", "in": "query", "description": "Email address of the referrer whose dashboard you require", "required": true, "schema": { "type": "string" }, "example": "jane.doe@example.com" }, { "name": "request[authenticationToken]", "in": "query", "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", "required": true, "schema": { "type": "string" }, "example": "[AUTHENTICATION-TOKEN]" }, { "name": "request[partnerCode]", "in": "query", "description": "Your partner code, used to link to your users and offers", "required": true, "schema": { "type": "string" }, "example": "[YOUR-PARTNER-CODE]" }, { "name": "request[situation]", "in": "query", "description": "Situation - a string representing where in the application you are making this request", "required": true, "schema": { "type": "string" }, "example": "mobile-app" }, { "name": "request[ipAddress]", "in": "query", "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.", "required": false, "schema": { "type": "string" } }, { "name": "request[localeCode]", "in": "query", "description": "Locale code - ISO standard locale code (e.g. en_GB) for the locale you expect the content to be in", "required": false, "schema": { "type": "string" } }, { "name": "segment", "in": "query", "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.", "required": false, "schema": { "type": "string" } }, { "name": "uniqueCustomerIdentifier", "in": "query", "description": "Customer Id - your unique identifier for this customer", "required": false, "schema": { "type": "string" } }, { "name": "request[userDeviceIdentifier]", "in": "query", "description": "User Device Identifier should be a unique reference to this combination of app + user.", "required": false, "schema": { "type": "string" } }, { "name": "request[deviceType]", "in": "query", "description": "Device type - your description of the device the user is using. We use this for performance and conversion optimisation.", "required": false, "schema": { "type": "string" } }, { "name": "request[appName]", "in": "query", "description": "Your application name. Used for reporting.", "required": false, "schema": { "type": "string" } }, { "name": "request[appVersion]", "in": "query", "description": "Your application version reference. Used for reporting and troubleshooting.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned when successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralDashboardOffer" } } } }, "204": { "description": "No content, when the customer does not have a dashboard to show. Try enrolling them as a referrer first." }, "400": { "description": "The request contains errors" }, "403": { "description": "Returned when the integration for this merchant is not enabled" }, "404": { "description": "Returned when it is not possible to serve a dashboard for this request" }, "500": { "description": "Internal server error, unable to complete the request" } } } }, "/api/consumer/{version}/referrer/search/content": { "get": { "tags": [ "Find referrer by name" ], "summary": "Find a friend content", "description": "Fetch details from Mention Me with which to build a \"find a friend\" page. This will include an initial CTA, such as \"Been referred by a friend?\" as well as specific content which you can use to build the page.\n\nUsing this API to build your content will allow you to keep your content up to date with the latest content managed in Mention Me.\n\nYou should call this API once when your page is loaded, e.g. on the checkout page, and use it to populate the page.", "operationId": "get_api_name_search_content", "parameters": [ { "name": "version", "in": "path", "description": "Version", "required": true, "schema": { "type": "string", "pattern": "v2|v1", "enum": [ "v2", "v1" ] }, "example": "v2" }, { "name": "request[partnerCode]", "in": "query", "description": "Your partner code, used to link to your users and offers", "required": true, "schema": { "type": "string" }, "example": "[YOUR-PARTNER-CODE]" }, { "name": "request[situation]", "in": "query", "description": "Situation - a string representing where in the application you are making this request", "required": true, "schema": { "type": "string" }, "example": "mobile-app" }, { "name": "request[localeCode]", "in": "query", "description": "Locale code - ISO standard locale code (e.g. en_GB) for the locale you expect the content to be in", "required": true, "schema": { "type": "string" } }, { "name": "request[userDeviceIdentifier]", "in": "query", "description": "User Device Identifier should be a unique reference to this combination of app + user.", "required": false, "schema": { "type": "string" } }, { "name": "request[deviceType]", "in": "query", "description": "Device type - your description of the device the user is using. We use this for performance and conversion optimisation.", "required": false, "schema": { "type": "string" } }, { "name": "request[appName]", "in": "query", "description": "Your application name. Used for reporting.", "required": false, "schema": { "type": "string" } }, { "name": "request[appVersion]", "in": "query", "description": "Your application version reference. Used for reporting and troubleshooting.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned when successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefereeContent" } } } }, "403": { "description": "Returned when the integration for this merchant is not enabled" }, "404": { "description": "Returned when it is not possible to an offer to render content for" }, "500": { "description": "The request contains errors" }, "503": { "description": "The service was unavailable, try again shortly" } } } }, "/api/consumer/{version}/referrer/search": { "get": { "tags": [ "Find referrer by name" ], "summary": "Find a friend", "description": "Search for a referrer by name (or email) to allow your customer to find their friend via NameShare.\n\nIf an exact match is found, we will return a 200 response. The 200 response will include the `referrerMentionMeIdentifier` and `referrerToken`. You should next collect the referee's details (i.e. their email address) and register them with the \"Register referee\" API. Completion of the registration with a valid email, `referrerMentionMeIdentifier` and `referrerToken` will allow the referee to gain their reward.\n\nIf no exact match is found, we will return a 404 response. A 404 may indicate we didn't find anyone, or it may indicate that we found multiple people with the same name. If we did find multiple people with the same name, we will also set the `foundMultipleReferrers` parameter in the root of the response to true.\n\nIf `foundMultipleReferrers` is set to true, the client should prompt the referee to narrow down the search, e.g. by entering the email address of the referrer. The exact narrowing strategy is up to the client.", "operationId": "get_api_name_search", "parameters": [ { "name": "version", "in": "path", "description": "Version", "required": true, "schema": { "type": "string", "pattern": "v2|v1", "enum": [ "v2", "v1" ] }, "example": "v2" }, { "name": "name", "in": "query", "description": "Name of a referrer to search for (entered by the new customer)", "required": true, "schema": { "type": "string" }, "example": "[REFERRERS-NAME]" }, { "name": "email", "in": "query", "description": "Optionally ask the new customer to qualify the name with an email address belonging to the referrer. We typically ask for a Name first and then if no matches found, offer Name + Email address.", "required": false, "schema": { "type": "string" } }, { "name": "request[partnerCode]", "in": "query", "description": "Your partner code, used to link to your users and offers", "required": true, "schema": { "type": "string" }, "example": "[YOUR-PARTNER-CODE]" }, { "name": "request[situation]", "in": "query", "description": "Situation - a string representing where in the application you are making this request", "required": true, "schema": { "type": "string" }, "example": "mobile-app" }, { "name": "request[ipAddress]", "in": "query", "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.", "required": false, "schema": { "type": "string" } }, { "name": "request[localeCode]", "in": "query", "description": "Locale code - ISO standard locale code (e.g. en_GB) for the locale you expect the content to be in", "required": true, "schema": { "type": "string" } }, { "name": "request[userDeviceIdentifier]", "in": "query", "description": "User Device Identifier should be a unique reference to this combination of app + user.", "required": false, "schema": { "type": "string" } }, { "name": "request[deviceType]", "in": "query", "description": "Device type - your description of the device the user is using. We use this for performance and conversion optimisation.", "required": false, "schema": { "type": "string" } }, { "name": "request[appName]", "in": "query", "description": "Your application name. Used for reporting.", "required": false, "schema": { "type": "string" } }, { "name": "request[appVersion]", "in": "query", "description": "Your application version reference. Used for reporting and troubleshooting.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned when successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferrerFound" } } } }, "403": { "description": "Returned when the integration for this merchant is not enabled" }, "404": { "description": "Returned when it is not possible to find a match for this search" }, "500": { "description": "The request contains errors" }, "503": { "description": "The service was unavailable, try again shortly" } } } }, "/api/consumer/{version}/referee/register": { "post": { "tags": [ "Link new customer to referrer" ], "summary": "Register referee", "description": "After a successful response from the \"Find friend\" API, this endpoint allows you to register a new customer to confirm the relationship between the Referee (the friend) and the Referrer (the person who referred them).\n\nConfirming the registration requires the `referrerMentionMeIdentifier` and `referrerToken` from the search API response.\n\nTo complete the registration, you will need to confirm the registration details of the referee via this API. This will grant the referee their reward, or will inform them on how to obtain one if further action is required\n(e.g. making a purchase).", "operationId": "post_api_register_referee", "parameters": [ { "name": "version", "in": "path", "description": "Version", "required": true, "schema": { "type": "string", "pattern": "v2|v1", "enum": [ "v2", "v1" ] }, "example": "v2" } ], "requestBody": { "description": "Details of the new customer who has been referred", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrolRefereeType" } } } }, "responses": { "200": { "description": "Returned when successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefereeRegister" } } } }, "400": { "description": "The request contains errors" }, "403": { "description": "Returned when the integration for this merchant is not enabled" }, "404": { "description": "Returned when the referrer is not found" }, "500": { "description": "Internal server error, unable to complete the request" } } } }, "/api/consumer/{version}/product/view": { "post": { "summary": "Track product page view for referral attribution.", "description": "Request body (JSON): - browserId (string, required): Client-generated browser fingerprint hash (djb2)\n- referrerId (string, optional): Referring user's visitorId from mm_rf URL param - currentUrl (string): Full URL of product page - host (string): Hostname - pathname (string): URL path - referrer (string): Document referrer or \"$direct\" - referringDomain (string): Referrer hostname or \"$direct\" - os (string): Operating system name - osVersion (string): OS version\n- browser (string): Browser name - device (string): Device identifier - deviceType (string): \"Mobile\", \"Tablet\", or \"Desktop\" - browserLanguage (string): Browser language (e.g., \"en-GB\")\n- screenHeight (int): Screen height in pixels - screenWidth (int): Screen width in pixels - viewportHeight (int): Viewport height in pixels - viewportWidth (int): Viewport width in pixels\n\nResponse: { visitorId: string } - SHA256(browserId + clientIP)", "operationId": "post_api_product_view", "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string", "pattern": "v2|v1", "enum": [ "v2", "v1" ] } } ], "responses": { "default": { "description": "" } } } }, "/api/consumer/{version}/product/share": { "post": { "summary": "Track product share action.", "description": "Request body (JSON): - visitorId (string, required): User's visitorId from /view response - currentUrl (string): Full URL being shared - (+ all tracking properties from viewAction)\n\nResponse: }", "operationId": "post_api_product_share", "parameters": [ { "name": "version", "in": "path", "required": true, "schema": { "type": "string", "pattern": "v2|v1", "enum": [ "v2", "v1" ] } } ], "responses": { "default": { "description": "" } } } } }, "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/api-reference/entry-point-api/postmessage", "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" }, "ConfirmOrderType": { "required": [ "order", "customer", "request" ], "properties": { "order": { "title": "Order", "description": "Information about the order which took place", "oneOf": [ { "$ref": "#/components/schemas/OrderDetails" } ] }, "customer": { "title": "Customer", "description": "Information about the customer who placed the order", "oneOf": [ { "$ref": "#/components/schemas/CustomerDetails" } ] }, "request": { "title": "Request", "description": "Information about the request", "oneOf": [ { "$ref": "#/components/schemas/Request" } ] }, "address": { "title": "Address", "description": "Information about the address of the customer who placed the order", "oneOf": [ { "$ref": "#/components/schemas/Address" } ] } }, "type": "object" }, "ConfirmOrderWithCouponType": { "required": [ "order", "request" ], "properties": { "order": { "title": "Order", "description": "Information about the order which took place", "oneOf": [ { "$ref": "#/components/schemas/OrderWithCouponType" } ] }, "customer": { "title": "Customer", "description": "Information about the customer who placed the order (if present)", "oneOf": [ { "$ref": "#/components/schemas/CustomerDetails" } ] }, "request": { "title": "Request", "description": "Information about the request", "oneOf": [ { "$ref": "#/components/schemas/Request" } ] }, "address": { "title": "Address", "description": "Information about the address of the customer who placed the order", "oneOf": [ { "$ref": "#/components/schemas/Address" } ] } }, "type": "object" }, "EnrolReferrerType": { "required": [ "customer", "request" ], "properties": { "customer": { "title": "Customer", "description": "Information about the referrer to enrol", "oneOf": [ { "$ref": "#/components/schemas/CustomerEnrolling" } ] }, "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, for segmentation", "oneOf": [ { "$ref": "#/components/schemas/AddressWithCountry" } ] } }, "type": "object" }, "ReferralShareOffer": { "properties": { "offer": { "title": "Description of the offer and rewards.", "oneOf": [ { "$ref": "#/components/schemas/Offer" } ] }, "nameShare": { "title": "Name Share information:", "description": "Details about NameShare, including the name someone can search for and their referral code if available.", "oneOf": [ { "$ref": "#/components/schemas/NameShare" } ] }, "shareLinks": { "title": "List of share links for different share mechanisms.", "type": "array", "items": { "$ref": "#/components/schemas/ShareLink" } }, "termsLinks": { "title": "Links to the terms and conditions for this offer.", "oneOf": [ { "$ref": "#/components/schemas/TermsLinks" } ] } }, "type": "object" }, "ReferralDashboardOffer": { "properties": { "offer": { "title": "Description of the offer and rewards.", "oneOf": [ { "$ref": "#/components/schemas/Offer" } ] }, "nameShare": { "title": "Name Share information:", "description": "Details about NameShare, including the name someone can search for and their referral code if available.", "oneOf": [ { "$ref": "#/components/schemas/NameShare" } ] }, "shareLinks": { "title": "List of share links for different share mechanisms.", "type": "array", "items": { "$ref": "#/components/schemas/ShareLink" } }, "termsLinks": { "title": "Links to the terms and conditions for this offer.", "oneOf": [ { "$ref": "#/components/schemas/TermsLinks" } ] }, "referralStats": { "title": "Referral Stats.", "oneOf": [ { "$ref": "#/components/schemas/ReferralStats" } ] }, "referralRewards": { "title": "Referral rewards - list of potential rewards they are due for introducing customers.", "type": "array", "items": { "$ref": "#/components/schemas/DashboardReward" } } }, "type": "object" }, "RefereeContent": { "properties": { "entryCta": { "title": "The Call to Action the user uses to start the journey.", "description": "e.g. \"Been referred by a friend?\"", "type": "string" }, "headline": { "title": "A headline to display to users when they open the NameSearch journey.", "description": "e.g. \"Who referred you to us?\"", "type": "string" }, "searchText": { "title": "A headline to display to users when they open the NameSearch journey.", "description": "e.g. \"Enter your friends name so we can thank them for referring you to us.\"", "type": "string" }, "searchCta": { "title": "The Call to Action on the button.", "description": "e.g. \"Find them\"", "type": "string" }, "nameInputPlaceholder": { "title": "A placeholder string to display in the name input field.", "description": "e.g. \"Your friend's name\"", "type": "string" }, "emailInputPlaceholder": { "title": "A placeholder string to display in the email input field.", "description": "e.g. \"Your friend's email\"", "type": "string" } }, "type": "object" }, "ReferrerFound": { "properties": { "referrer": { "title": "The primary payload of the response, assuming we found the referrer successfully. If we didn't this will be empty.", "oneOf": [ { "$ref": "#/components/schemas/ReferrerIdentifier" } ] }, "foundMultipleReferrers": { "title": "Whether the user should be prompted to narrow the search (by entering an email address for example)", "type": "boolean" }, "links": { "title": "Pagination of output and links to associated resources, including content-collection items.", "type": "array", "items": { "$ref": "#/components/schemas/ContentCollectionLink" } }, "termsLinks": { "title": "Links to the terms and conditions for this offer.", "oneOf": [ { "$ref": "#/components/schemas/TermsLinks" } ] }, "meta": { "title": "This is used to hold a meta status code which is then used to pass a response back to the actual response later.", "type": "object", "additionalProperties": true } }, "type": "object" }, "EnrolRefereeType": { "required": [ "referrerMentionMeIdentifier", "referrerToken", "customer", "request" ], "properties": { "referrerMentionMeIdentifier": { "description": "Id representing the referrer returned by a successful name search", "type": "integer", "example": "" }, "referrerToken": { "description": "Token representing the referrer returned by a successful name search", "type": "string", "example": "" }, "customer": { "title": "Customer", "description": "Information about the referee to register and give a reward", "oneOf": [ { "$ref": "#/components/schemas/CustomerDetails" } ] }, "request": { "title": "Request", "description": "Information about the request", "oneOf": [ { "$ref": "#/components/schemas/Request" } ] } }, "type": "object" }, "RefereeRegister": { "properties": { "offer": { "$ref": "#/components/schemas/Offer" }, "refereeReward": { "title": "A description of the referee reward for the Referee", "default": null, "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/RefereeReward" } ] }, "content": { "$ref": "#/components/schemas/ContentCollectionLink" }, "termsLinks": { "title": "Links to the terms and conditions for this offer.", "oneOf": [ { "$ref": "#/components/schemas/TermsLinks" } ] }, "status": { "type": "string" } }, "type": "object" }, "OrderWithCouponType": { "required": [ "orderIdentifier", "total", "currencyCode", "dateString", "couponCode" ], "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": "The coupon that was used in the transaction. 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" }, "Offer": { "properties": { "id": { "title": "The identifier of the offer.", "type": "integer" }, "localeCode": { "title": "The locale code of the Offer.", "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" }, "callToAction": { "title": "The callToAction text of the Offer - typically goes on the button of the offer", "description": "e.g. \"Get a £20 gift card\"", "type": "string" }, "privacyNotice": { "title": "The privacyNotice text of the Offer - typically shown near the CTA if required by privacy regulation", "description": "e.g. \"Get a £20 gift card\"", "type": "string" }, "privacyLink": { "title": "The URL to the Mention Me privacy policy - typically shown near the Privacy Notice.", "description": "e.g. \"https://mention-me.com/help/privacy_policy\"", "type": "string" }, "referrerReward": { "title": "The explicit description of the Referrer Reward for the Referrer.", "oneOf": [ { "$ref": "#/components/schemas/Reward" } ] }, "refereeReward": { "title": "The explicit description of the Referee reward for the Referrer.", "oneOf": [ { "$ref": "#/components/schemas/Reward" } ] } }, "type": "object" }, "NameShare": { "properties": { "name": { "type": "string" }, "referralCode": { "title": "External docs:", "description": "Unique code this person can share with others to enter in the \"Been referred by a friend?\" section of your website.", "type": "string" } }, "type": "object" }, "ShareLink": { "properties": { "type": { "title": "The type of share mechanism (e.g. Facebook, Twitter, Open link, Email link)", "type": "string" }, "protocol": { "title": "The protocol (if available) for the share", "type": "string" }, "url": { "title": "The url to include in the share", "type": "string" }, "defaultShareMessage": { "title": "The default message to include in the share", "type": "string", "default": "" }, "exampleImplementation": { "title": "An example of the share URL you could use to initiate this share. You are free to implement this your own way if you wish.", "type": "string", "default": "" } }, "type": "object" }, "TermsLinks": { "properties": { "localeCode": { "title": "The locale code of the terms link", "type": "string" }, "linkToTermsInLocale": { "title": "Link to the terms and conditions in the locale stated", "type": "string" } }, "type": "object" }, "ReferralStats": { "properties": { "successfulReferrals": { "title": "Number of successful referrals", "type": "integer", "default": 0 }, "invitations": { "title": "Number of invitations made", "type": "integer", "default": 0 }, "clicksOnInvites": { "title": "Number of clicks on invites", "type": "integer", "default": 0 } }, "type": "object" }, "DashboardReward": { "properties": { "description": { "title": "Friendly description of a reward for the intended recipient.", "description": "The description we give may vary depending on the point in the flow that we choose to give it. Note that in some cases this might be \"promising the reward\" and in other cases \"giving it\".\n\ne.g. \"You'll get £20 for each friend you refer\" e.g. \"Your friends get a free camera when they order for the first time\" e.g. \"A 20% discount code\"", "type": "string" }, "summary": { "title": "Summary - now deprecated - it serves no purpose over and above the description.", "type": "string" }, "amount": { "title": "The reward amount - now deprecated (because rewards don't have a consistent amount - some have text, percentage, number. Use the description to describe the reward.", "type": "string" }, "status": { "title": "Status of the reward eg Pending, Cancelled, Given by email", "type": "string" }, "forReferring": { "title": "Description of who they referred to get the reward. As this could be multiple people, it's an array.", "type": "object", "additionalProperties": true } }, "type": "object" }, "ReferrerIdentifier": { "properties": { "referrerMentionMeIdentifier": { "title": "Our identifier for the referrer identified, the customer ID", "type": "integer" }, "referrerToken": { "title": "Token used to identify the referrer uniquely\n(flowId)", "type": "string" }, "referrerOfferIdentifier": { "title": "Identify the Offer (i.e. this is an Offer Id)", "type": "integer" }, "offer": { "title": "Description of the offer and rewards which this referrer is able to offer", "default": null, "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/Offer" } ] } }, "type": "object" }, "ContentCollectionLink": { "properties": { "relationship": { "title": "Relationship of the link between the two resources", "type": "string", "default": "content-collection" }, "resource": { "title": "The target resource being linked", "type": "array", "items": { "$ref": "#/components/schemas/Content" } } }, "type": "object" }, "RefereeReward": { "properties": { "description": { "title": "Description of the reward", "type": "string" }, "couponCode": { "title": "Reward coupon code (if appropriate)", "type": "string" }, "securityCode": { "title": "Reward security code (if appropriate)", "type": "string" }, "url": { "title": "Reward link (if appropriate)", "type": "string" }, "amount": { "title": "The reward amount - note this is not always a number. It can be a currency amount, a percentage, a number (of items) or a text description depending on the reward type.", "type": "string" } }, "type": "object" }, "Reward": { "properties": { "description": { "title": "Friendly description of a reward for the intended recipient.", "description": "The description we give may vary depending on the point in the flow that we choose to give it. Note that in some cases this might be \"promising the reward\" and in other cases \"giving it\".\n\ne.g. \"You'll get £20 for each friend you refer\" e.g. \"Your friends get a free camera when they order for the first time\" e.g. \"A 20% discount code\"", "type": "string" }, "summary": { "title": "Summary - now deprecated - it serves no purpose over and above the description.", "type": "string" }, "amount": { "title": "The reward amount - now deprecated (because rewards don't have a consistent amount - some have text, percentage, number. Use the description to describe the reward.", "type": "string" } }, "type": "object" }, "Content": { "properties": { "key": { "title": "The content key", "type": "string" }, "content": { "title": "The content string", "type": "string" } }, "type": "object" } } }, "tags": [ { "name": "Record Order" }, { "name": "Enrol Referrer" }, { "name": "Get referrer dashboard" }, { "name": "Find referrer by name" }, { "name": "Link new customer to referrer" } ] }