SFTP Data Formats

Overview

This page describes the different types of data that can be sent to Mention Me via SFTP. All data must be in structured CSV format.

For connection details and folder structure, see .

Column names are case sensitive and use PascalCase. Columns whose names do not match the expected values exactly will be ignored on import. The type values are also fixed strings: they must match exactly or the row will be rejected.

Columns may be supplied in any order, so CustomerFirstname,CustomerSurname is equivalent to CustomerSurname,CustomerFirstname.

Data Types

Mention Me accepts several types of inbound data via SFTP. The type column on each row selects which feed the row belongs to.

Order / Transaction Data (type: order)

Used to send order or transaction data for conversion tracking. Each row represents a single order. This is commonly used for orders that cannot be captured by the JavaScript tag, such as orders placed over the phone or in a customer support application.Required fields:

string

required

Must be order. Example: order

string

required

The customer’s email address. Example: customer@example.com

string

required

Unique order identifier. Example: ORD-12345

string

required

Date and time of the order (ISO 8601). Example: 2024-01-15T10:30:00Z

string

required

Order total excluding VAT/taxes and delivery. Example: 49.99

string

required

ISO 4217 currency code. Example: GBP

Recommended fields (improve referral performance):

string

The coupon code used by the customer (if any). Example: REF-ABC123

string

Whether this order is for a subscription (recurring). Helps us qualify and categorise the revenue. Example: false

string

Whether this is the customer’s first order initiating a subscription. Example: false

string

Whether this order is a gift (bought for someone else). Gifts can be signals of advocacy. Example: false

string

The discount amount, assumed already deducted from the order total. Lets us calculate cost per acquisition. Example: 18.45

string

The number of items in the order. Helps us understand the type of purchase. Example: 3

string

First line of the customer’s address. Example: 1-45 Durham Street

string

Second line of the customer’s address. Example: VG01

string

City of the customer’s address. Example: London

string

County or state of the customer’s address. Example: London

string

Postcode or zip code of the customer’s address. Example: SE11 5JH

string

Country of the customer’s address. Example: United Kingdom

Optional fields:

string

Your internal customer identifier. Example: CUST-789

string

Customer’s first name. Example: Alice

string

Customer’s last name. Example: Liddell

string

The segment this customer is in. Example: VIPs

string

Locale code. Example: en_GB

string

Extra custom data used to qualify or segment the order. Example: NewCustomer|AccountID#1234

For ongoing subscription order data where you prefer not to send any PII, CustomerEmail can be replaced with CustomerHashedEmail. This requires that you follow the hashing instructions in the Hashing historical customer emails guide. When CustomerHashedEmail is used, no referees or referrers will be rewarded.

Customer Registrations (type: register / register-silently)

Used to enrol customers into the referral programme, for example customers who have confirmed they wish to take part. The type value determines whether a confirmation email is sent: use register to send a welcome email, or register-silently to register the customer without contacting them.

For GDPR compliance, only use this feed if you are certain you have the right to share this data, for example where customers have been told their data is shared for the purpose of running a referral programme. register-silently is preferred over register unless you have specific consent to send the customer referral emails.

Required fields:

string

required

register or register-silently. Example: register

string

required

The customer’s email address. Example: customer@example.com

string

required

Customer’s first name. Example: Jane

string

required

Customer’s last name. Example: Smith

Optional fields:

string

Your internal customer identifier. Example: CUST-789

string

The locale of the referral campaign the customer should be enrolled into. Example: fr_CA

string

The segment this customer is in. Example: VIPs

string

Associated order. Example: ORD-12345

string

Order date. Example: 2024-01-15T10:30:00Z

string

Order total. Example: 49.99

string

Currency. Example: GBP

string

Voucher used. Example: REF-ABC123

Cancelled Referees (type: referee-cancelled)

Used to notify Mention Me that a new customer has cancelled their order, so any pending referrer reward can be withheld.Required fields:

string

required

Must be referee-cancelled. Example: referee-cancelled

string

required

Email address of the customer who cancelled their order. Example: customer@example.com

Optional fields:

string

The cancelled order ID. Example: ORD-12345

Example:

type,CustomerEmail
referee-cancelled,alice.bloggs@example.com
referee-cancelled,joe.bloggs@example.com

Eligible Referees (type: referee-eligible)

In many cases the eligibility of a customer to earn a reward depends on more than just making a purchase. For example, the customer may have to keep a subscription for more than 30 days or pass an external fraud check.The eligibility feed lets you tell Mention Me about each customer who may have met the criteria to be rewarded. It is important that all potentially eligible customers are provided, as only Mention Me knows whether they are due a reward.Required fields:

string

required

Must be referee-eligible. Example: referee-eligible

Plus one of the following identifiers for the customer:

string

Email address of the potentially eligible customer. Example: customer@example.com

string

Your internal ID of the potentially eligible customer. Example: 123456-example

string

The order ID placed by the potentially eligible customer. Example: O123X4

Examples:By Customer Email:

type,CustomerEmail
referee-eligible,alice.bloggs@example.com
referee-eligible,joe.bloggs@example.com

By Customer ID:

type,CustomerId
referee-eligible,123alice
referee-eligible,345joe

By Order ID:

type,OrderId
referee-eligible,O123X4
referee-eligible,O123C5

Coupon Redemption (type: coupon-redemption)

Used to confirm referral purchases completed in store via a coupon. Referral can drive customers into your stores to make their first purchase: the referral happens before the purchase and the referee is given a single-use voucher to use in store. This feed sends back confirmation that the code was used and the details of the purchase. Because you may not have the customer’s email address, the feed only requires the coupon code plus the transaction details.If you have collected the customer’s email address you may include it, and we will record both the original referee email and the one used to confirm the purchase.Required fields:

string

required

Must be coupon-redemption. Example: coupon-redemption

string

required

The coupon code used by the customer in the transaction. Example: REF-ABC123

string

required

Unique order or transaction identifier. Example: TXN-789

string

required

Date and time of the order (ISO 8601). Example: 2024-01-15T10:30:00Z

string

required

Transaction value excluding VAT/taxes and delivery. Example: 75.00

string

required

ISO 4217 currency code. Example: GBP

Recommended fields (improve referral performance):

string

Whether this order is for a subscription (recurring). Example: false

string

Whether this is the customer’s first order initiating a subscription. Example: false

string

Whether this order is a gift. Example: false

string

The discount amount, assumed already deducted from the order total. Example: 18.45

string

The number of items in the order. Example: 3

Optional fields:

string

Your internal customer identifier. Example: CUST-789

string

The customer’s email address, if collected. Example: customer@example.com

string

The segment this customer is in. Example: VIPs

Example:

type,MerchantCouponCode,OrderId,OrderDate,OrderTotal,OrderCurrency
coupon-redemption,PM012422452,INV100032313,2024-01-15T10:30:00Z,17.99,GBP
coupon-redemption,INSTORE-ABJ124152,INV100032314,2024-01-16T11:00:00Z,44.05,GBP

Customer Details Changed (type: customer-details-changed)

Used to notify Mention Me of customer account changes, for example a name or email address update, so the customer’s referral history is preserved against their new details. This is most common in subscription businesses such as the energy sector.Required fields:

string

required

Must be customer-details-changed. Example: customer-details-changed

string

required

The current email address of the customer as Mention Me currently knows it. Example: old@example.com

Plus at least one of the following fields, holding the new value:

string

The new email address of the customer. Example: new@example.com

string

The internal ID Mention Me should use for this customer from now on. Example: AW79302

string

The first name Mention Me should use from now on. Example: Alice

string

The surname Mention Me should use from now on. Example: Wonderland

Example:The first row below changes Alice’s surname and email address. The second changes only Joe’s first name.

type,CustomerEmail,NewCustomerEmail,CustomerFirstname,CustomerSurname
customer-details-changed,alice.liddell@example.com,alice.wonderland@example.com,Alice,Wonderland
customer-details-changed,joe.bloggs@example.com,,Joseph,

Lapsed Customers (type: customer-lapsed)

Relevant for subscription businesses only.

Used to inform Mention Me that a customer has stopped paying for a service or subscription. This supports models where a lapsed customer can be given a referral offer if they are referred and return as a paying customer after a period of time.Required fields:

string

required

Must be customer-lapsed. Example: customer-lapsed

string

required

Email address of the customer who has lapsed. Example: customer@example.com

Example:

type,CustomerEmail
customer-lapsed,alice.bloggs@example.com
customer-lapsed,joe.bloggs@example.com

Incentivised Actions (type: incentivised-action)

Used to record when a customer has completed a non-order action that should trigger a reward or progress in your referral programme, for example signing up for a newsletter, leaving a review, or registering an account.Required fields:

string

required

Must be incentivised-action. Example: incentivised-action

string

required

Email address of the customer who completed the action. Example: customer@example.com

string

required

The identifier, provided by Mention Me, that identifies the action performed. Example: i5d88c29eb14e7

Example:The following example shows alice.liddell@example.com completing action i5d88c29eb14e7, which corresponds to an action defined inside Mention Me (for example, completing a review).

type,CustomerEmail,ActionId
incentivised-action,alice.liddell@example.com,i5d88c29eb14e7

Purge (type: purge)

Used to permanently remove all records of a specific customer, including all Personally Identifiable Information. This can be used to satisfy a data-subject erasure request.

This action is irreversible.

Required fields:

string

required

Must be purge. Example: purge

string

required

Email address of the customer to purge. Example: customer@example.com

Example:

type,CustomerEmail
purge,alice.bloggs@example.com
purge,joe.bloggs@example.com

File Format Requirements

Format: CSV with headers
Encoding: UTF-8
Delimiter: Comma (,)
Line endings: Unix (\n) or Windows (\r\n)
Quoting: Fields containing commas, quotes, or newlines must be double-quoted
Column names: PascalCase, case sensitive. Mis-named columns are silently ignored on import
Column order: Columns may be supplied in any order
Mixed feeds: A single file may contain rows with different type values; each row is processed according to its type

File Naming

Any filename can be used, but each file must be unique. We recommend including a date in the filename, for example Orders-20240115.csv.

Errors and Malformed Data

Malformed or incorrect data is handled as follows. Missing columns or column headers

A file missing a column header will not be processed.
A file missing a mandatory column, or with the column incorrectly named, will be ignored.
A file missing an optional column, or with an optional column incorrectly named, will be processed as if the optional column was not present.

Missing or malformed rows Each row is treated as a separate entity, so errors in one row do not affect another. A malformed row (for example, an empty row, or a row with an email address that has no @ symbol) will be ignored, and the remainder of the file will be processed as normal.

Need Help?

Start a conversation with the in-platform Support widget in the bottom-right corner of your dashboard - it can usually answer this straight away. If it can’t, raise a request via the request form.

Tag Integration

Advanced

MCP Server

Overview

Data Types

File Format Requirements

File Naming

Errors and Malformed Data

Need Help?

​Overview

​Data Types

​File Format Requirements

​File Naming

​Errors and Malformed Data

​Need Help?

Overview

Data Types

File Format Requirements

File Naming

Errors and Malformed Data

Need Help?