Developers

REST API Overview

The Friendbuy REST API provides merchants with the ability to access shares, conversions, and referral codes. Shares and conversions can be found by campaign or within a date range. Clients can generate and lookup referral codes for users within a campaign. Clients with mobile applications not using traditional JavaScript widgets for tracking conversions can use the API to inform Friendbuy of purchases for conversion tracking.

General Information

API Base URL

The base URL is https://api.friendbuy.com/v1

Summary of Endpoints

Endpoint Description
GET /shares Search for shares
POST /shares Create a new Share
GET /shares/{id} Get details on a particular share
GET /conversions Search for conversions
GET /conversions/{id} Get details on a particular conversion
POST /purchases Inform Friendbuy of a purchase that generates a conversion
POST /referral_codes Create a referral code (for a customer and campaign)
GET /referral_codes/{code} Get the customer/campaign or share associated with the given code
PATCH /referral_codes/{code} Update custom parameters associated with the given code
GET /customers Search for customers
GET /customers/{id} Get details on a particular customer
GET /customers/{id}/shares Get shares made by a particular customer
GET /customers/{id}/referral_codes Get referral codes for a particular customer
GET /customers/{id}/email-recipients Get data about friends invited via e-mail by a particular customer
GET /customers/{id}/conversions Get conversions associated with a particular customer
GET /customers/{id}/rewards Get rewards associated with a particular customer
GET /opt_outs/emails Get email opt outs
POST /opt_outs/emails Create new email opt outs (from a list of email addresses)
GET /opt_outs/email_update/{id} Retrieve the status of a request to create email opt outs

Authentication and Keys

All API endpoints use basic authentication over HTTPS. You can find your access key (to use as the username) and your secret key (to use as the password) by going to Settings => Admin => API Keys in your Friendbuy account.

Headers

All POST requests require the Content-Type header be set to application/json.

Pagination

All search requests returning lists of objects should be paginated, using the query parameters offset (the number of results to skip) and limit (the maximum number of results to return). For example, if you wish to retrieve 50 shares at a time, you would make the following series of requests:

  • /shares?offset=0&limit=50
  • /shares?offset=50&limit=50
  • /shares?offset=100&limit=50
  • etc.

If offset is not supplied, it will default to 0. If limit is not supplied it will default to 100. If limit is set to a value greater than 1000, it will be truncated to 1000.

Dates and Datetimes

All dates and datetimes are to be specified in ISO-8601 format, for example 2015-02-28 (date) and 2017-11-24T08:31:22.7666-08:00 (datetime). Many search request endpoints support the parameters from_date and to_date to find entities within a date range.

API Details

GET /shares?campaign=&from_date=&to_date=&offset=&limit=

Retrieves shares, optionally restricted to those shares in a given campaign or to shares within a specific date range. The result contains an array of basic share data, having the form:

If searching for shares within a campaign, find the unique identifier for the campaign on the Campaigns page in your Friendbuy account.

{
    "total_results_count": 20021,
    "this_page_results_count": 50,
    "offset": 0,
    "results": [
        {
            "created_at": "2014-06-20T10:29:34.027109-05:00",
            "detail_uri": "https://api.friendbuy.com/v1/shares/43424",
            "ip_address": "1.1.1.1",
            "message": {
                "id": "53647261523",
                "content": "These are amazing shoes",
                "network": "email"
            },
            "sharer": {
                "customer": {
                    "first_name": "example",
                    "last_name": "example",
                    "account_id": "3",
                    "id": "3",
                    "email": "email@example.org",
                    "detail_uri": "https://api.friendbuy.com/v1/customers/8889"
                },
                "email": "cc@example.com",
                "facebook_friends_count": 2760,
                "name": "Claire C",
                "twitter_followers_count": 932112
            },
            "campaign": {
                "created_at": "2013-09-27T13:10:36.144318-08:00",
                "name": "Fall shoe clearance",
                "published": false,
                "referral_incentive": null
            }
        },
        . . .
    ]
}
POST /shares

Create a new Share for the given campaign. Shares created from this request may only be distributed via email at this time. The email will be sent on behalf of the accounts Sender Configuration. The campaign_id must belong to a campaign that is currently published. This resource accepts a JSON POST body in this form:

{
  "campaign_id": 123,
  "from_email_address": "sharer@example.com",
  "email_recipients": [
    "email1@example.com",
    "email2@example.com"
  ],
  "custom_message": "your optional share message",
  "customer": {
    "account_id": "12345",
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doh",
    "stripe_customer_id": "abcdefg123"
  }
}
custom_message

An optional custom message to include with the e-mail share.

customer

If the share should be associated with a new or existing customer, a customer object may optonally be specified. At minimum, a customer must contain an account_id. If an account_id belongs to an existing customer, all given fields will update the existing customer resource in Friendbuy.

Response Description
201 Created On success, Friendbuy will create a share. The response body will be a JSON representation of the created share as in GET /shares/{id}.
400 Bad Request If there are problems such as missing required parameters or an improperly formatted request body, an error response is returned with information about the cause of the problem.
GET /shares/{id}

Retrieves details on a single share. The URI for a share detail is obtained from the detail_uri attribute contained in a user search result. The response has the form:

{
    "id": 420,
    "created_at": "2013-04-18T10:34:30.951885+02:00",
    "referral_code": "dCOYe",
    "ip_address": "8.8.8.8",
    "message": {
        "id": "3251627463",
        "content": "These are amazing shoes",
        "network": "facebook"
    },
    "purchase": {
        "date": "2013-04-18T10:30:20.374623+02:00",
        "order_id": "8463164191",
        "total": "255.99"
    },
    "sharer": {
        "birthdate": "1952-10-07",
        "customer": {
            "first_name": "example",
            "last_name": "example",
            "account_id": "3",
            "id": "3",
            "email": "email@example.org",
            "detail_uri": "https://api.friendbuy.com/v1/customers/299"
        },
        "email": "jane@example.com",
        "facebook_friends_count": 139328,
        "name": "Jane Doe",
        "twitter_followers_count": 1420
    },
    "campaign": {
        "id": 2218,
        "created_at": "2013-03-05T12:15:57.000135-08:00",
        "name": "Spring Collection Offer",
        "published": true,
        "referral_incentive": {
            "type": "shopper_fixed_revenue",
            "value": "10.00"
        }
    }
}
GET /conversions?campaign=&from_date=&to_date=&offset=&limit=

Retrieves conversions, optionally restricted to those within a specific time period or from a specific campaign. The result contains an array of basic conversion data. Conversions will have either a share property or a personal_url property, depending on the type of conversion. The result will have the following form (both a share conversion and a personal url conversion are shown):

If searching for conversions within a campaign, find the unique identifier for the campaign on the Campaigns page in your Friendbuy account.

Notes on Fraud Detection

Friendbuy uses the following properties to determine if a conversion is the result of a possible self referral. If any of them are true, then the value of "possible_self_referral" in the response will be true.

Attribute Description
same_shopper This attribute reflects Friendbuy's internal method of detecting self-referral, which is independent of the information received from the merchant. This attribute can have a value of true or false.
same_customer This attribute will have a value of true if the customer_id for the referrer is the same as the customer_id for the person that made the purchase. Otherwise, it will have a value of false.
same_email This attribute will have a value of true if the email of the referrer is the same as the email of the person that made the purchase. Otherwise, it will have a value of false.
{
    "this_page_results_count": 2,
    "total_results_count": 10,
    "offset": 9,
    "results": [
        {
            "created_at": "2013-04-18T10:36:35.670131-07:00",
            "detail_uri": "https://api.friendbuy.com/v1/conversions/2885",
            "possible_self_referral": false,
            "fraud": {
                "same_shopper": false,
                "same_customer": false,
                "same_email": false
            },
            "purchase": {
                "order_id": "8806679207",
                "date": "2013-04-18T10:37:01.000241-07:00",
                "total": "5.95",
                "new_customer": true,
                "email": "email@example.org",
                "ip_address": "4.8.15.16"
            },
            "referrer": {
                "birthdate": "1952-10-07",
                "created_at": "2013-02-02T17:36:19.101606-00:00",
                "customer": {
                      "first_name": "example",
                      "last_name": "example",
                      "account_id": "3",
                      "id": "3",
                      "email": "email@example.org",
                      "detail_uri": "https://api.friendbuy.com/v1/customers/299"
                },
                "email": "jane@example.com",
                "facebook_friends_count": 139328,
                "name": "Jane Doe",
                "twitter_followers_count": 1420
            },
            "reward": "10.00",
            "share": {
                "id": 2342,
                "created_at": "2013-04-18T10:34:30.951885-07:00",
                "referral_code": "dCOYe",
                "detail_uri": "https://api.friendbuy.com/v1/shares/7103",
                "ip_address": "22.4.79.103",
                "message": {
                    "id": "9283746578",
                    "content": "I found some amazing bargains here!",
                    "network": "facebook"
                },
                "purchase": {
                    "date": "2013-04-18T10:30:20.374623+02:00",
                    "order_id": "8463164191",
                    "total": "255.99"
                },
                "sharer": {
                    "birthdate": "1952-10-07",
                    "customer": {
                        "first_name": "example",
                        "last_name": "example",
                        "account_id": "3",
                        "id": "3",
                        "email": "email@example.com",
                        "detail_uri": "https://api.friendbuy.com/v1/customers/299"
                    },
                    "email": "jane@example.com",
                    "facebook_friends_count": 139328,
                    "name": "Jane Doe",
                    "twitter_followers_count": 1420
                }
            },
            "status": "paid",
      "rewards": [
                {
                    "status": "valid",
                    "created_at": "2013-04-18T10:36:35.670131-07:00",
                    "rejected_reasons": null,
                    "amount": "10.00",
                    "type": "fixed_cash",
                    "id": 301118
                }
            ],
            "campaign": {
                "id": 2218,
                "created_at": "2013-03-05T12:15:57.000135-08:00",
                "name": "Spring Collection Offer",
                "published": true,
                "referral_incentive": {
                    "type": "shopper_fixed_revenue",
                    "value": "10.00"
                }
            }
        },
        {
            "created_at": "2013-04-18T11:53:49.758106-07:00",
            "detail_uri": "https://api.friendbuy.com/v1/conversions/2950",
            "personal_url": {
                "referral_code": "bZ",
                "destination_url": "www.example.com/products/995",
                "trackable_link": "http://fbuy.me/bZ"
            },
            "purchase": {
               "date": "2013-04-18T11:54:19.751262-07:00",
               "order_id": "0991867562",
                "total": "752.94"
            },
            "referrer": {
                "customer": {
                    "first_name": "example",
                    "last_name": "example",
                    "account_id": "C-234523523",
                    "id": "C-234534533"
                    "email": null,
                    "detail_uri": "https://api.friendbuy.com/v1/customers/11234"
                },
                "email": "customer@example.com",
                "facebook_friends_count": 10,
                "name": "Zoe Doe",
                "twitter_followers_count": 40
            },
            "reward": "3.5",
            "status": "unmarked",
            "rewards": [
                {
                    "status": "valid",
                    "created_at": "2013-04-18T11:54:19.751262-07:00",
                    "rejected_reasons": null,
                    "amount": "10.00",
                    "type": "fixed_cash",
                    "id": 301119
                }
            ],
            "campaign": {
                "id": 50,
                "created_at": "2013-03-05T12:15:57.000135",
                "name": "Garden Tool Clearance",
                "published": true,
                "referral_incentive": {
                    "type": "shopper_revenue_share",
                    "value": "10"
                }
            }
        }
    ]
}
GET /conversions/{id}

Retrieves details of a specific conversion. The conversion detail format is identical to the conversion stubs produced in the conversion search endpoint, except that:

  • There is no detail_uri field
  • The referrer property has the expanded customer form returned by GET /customer/{id}
  • The share property has the expended share form returned by GET /shares/{id}
POST /purchases

Notifies Friendbuy of a purchase that generates a conversion. Post a JSON document of the form:

{
    "order": { "id": "281", "amount": 795.00, "email": "email@example.org", "new_customer": true },
    "referral_code": "reN",
    "customer": { "id": "C9997", "account_id": "C9997", "email": "email@example.org", "first_name": "John", "last_name": "Doe" },
    "products": [
        { "sku": "ABC", "price": 225.16, "quantity": 2 },
        . . .
    ]
}

Note:

  • The submitted purchase MUST have values for order and referral_code.
  • customer should contain the ID of the customer making the purchase and the email address of that customer (if available).
  • For each product, only the sku is required.

The response may be one of the following:

  • On success, Friendbuy will create a conversion. The response code is 201 CREATED and the response body will be a JSON representation of the created conversion as in GET /conversions/{id}.
  • If the order_id has already been processed at Friendbuy, no conversion will be created and a response code of 409 CONFLICT is returned, and the body contains an error message.
  • If there are problems such as missing required parameters or an improperly formatted request body, a 400 BAD REQUEST is returned.
POST /referral_codes

Generates a referral code for a customer within a campaign (or retrieve the code if it already exists). Post a JSON document in your request as in the following example.

{
    "customer": {"id": "C9997", "account_id": "C9997", "email": "test@test.org", "first_name": "John", "last_name": "Doe"},
    "campaign": {"id": 2544}
}

Alternatively, just use an email address:

{
    "email": "test@test.org",
    "campaign": {"id": 1234}
}

The campaign ID to post can be found in the Campaigns page in your Friendbuy account.

If a referral code already exists for the customer/campaign pair it will be returned (with HTTP status code 200), otherwise a new code will be generated and returned (with HTTP status code 201). The response will contain information about the (new or existing) referral code. Referral codes may be attached to personal urls or to shares. An example response for personal urls is:

{
    "referral_code": "reN",
    "type": "personal_url",
    "campaign": {
        "id": 2544,
        "name": "Fall sale",
        "published": true,
        "referral_incentive": {
            "type": "shopper_fixed_revenue",
            "value": "10.00"
        },
        "created_at": "2014-07-25T13:59:52.328016-07:00"
    },
    "customer": {
        "first_name": "John",
        "last_name": "Smith",
        "recent_referral_codes": [
            {
                "referral_code": "cuIFR",
                "trackable_link": "http://fbuy.me/cuIFR",
                "destination_url": "http://friendbuy.com"
            },
            {
                "referral_code": "cuyO2",
                "trackable_link": "http://fbuy.me/cuyO2",
                "destination_url": "http://friendbuy.com"
            },
            {
                "referral_code": "cao1",
                "trackable_link": "http://fbuy.me/cao1",
                "destination_url": "http://friendbuy.com"
            }
        ],
        "created_at": "2015-03-24T17:33:57.693976",
        "email": "test@example.org",
        "recent_shares": [
            {
                "campaign": {
                    "id": 2544,
                    "name": "Fall sale",
                    "published": true,
                    "referral_incentive": {
                        "type": "shopper_fixed_revenue",
                        "value": "10.00"
                    },
                    "created_at": "2014-07-25T13:59:52.328016-07:00"
                },
                "created_at": "2015-06-09T17:45:26.164477-07:00",
                "referral_code": "aA",
                "sharer": {
                    "customer": {
                        "first_name": "John",
                        "last_name": "Smith",
                        "id": "402820419",
                        "detail_uri": "https://api.friendbuy.com/v1/customers/14681023",
                        "email": "test@example.org"
                    },
                    "facebook_friends_count": 0,
                    "twitter_followers_count": 0,
                    "name": "John Smith",
                    "email": "test@example.org"
                },
                "email": "test@example.org",
                "message": {
                    "content": "Check it out!",
                    "network": "email"
                },
                "ip_address": "127.0.0.1",
                "id": 3084914,
                "detail_uri": "https://api.friendbuy.com/v1/shares/3084914"
            },
            {
                "campaign": {
                    "id": 2544,
                    "name": "Fall sale",
                    "published": true,
                    "referral_incentive": {
                        "type": "shopper_fixed_revenue",
                        "value": "10.00"
                    },
                    "created_at": "2014-07-25T13:59:52.328016-07:00"
                },
                "created_at": "2015-06-09T17:45:26.164477-07:00",
                "referral_code": "bB",
                "sharer": {
                    "customer": {
                        "first_name": "John",
                        "last_name": "Smith",
                        "id": "402820419",
                        "detail_uri": "https://api.friendbuy.com/v1/customers/14681023",
                        "email": "test@example.org"
                    },
                    "facebook_friends_count": 0,
                    "twitter_followers_count": 0,
                    "name": "",
                    "email": "test@example.org"
                },
                "email": "test@example.org",
                "message": {
                    "content": "You should try this.",
                    "network": "email"
                },
                "ip_address": "127.0.0.1",
                "id": 2797183,
                "detail_uri": "https://api.friendbuy.com/v1/shares/2797183"
            },
            {
                "campaign": {
                    "id": 2544,
                    "name": "Fall sale",
                    "published": true,
                    "referral_incentive": {
                        "type": "shopper_fixed_revenue",
                        "value": "10.00"
                    },
                    "created_at": "2014-07-25T13:59:52.328016-07:00"
                },
                "created_at": "2015-06-09T17:45:26.164477-07:00",
                "referral_code": "cC",
                "sharer": {
                    "customer": {
                        "first_name": "John",
                        "last_name": "Smith",
                        "id": "402820419",
                        "detail_uri": "https://api.friendbuy.com/v1/customers/14681023",
                        "email": "test@example.org"
                    },
                    "facebook_friends_count": 0,
                    "twitter_followers_count": 0,
                    "name": "John Smith",
                    "email": "test@example.org"
                },
                "email": "test@example.org",
                "message": {
                    "content": "You might like this.",
                    "network": "email"
                },
                "ip_address": "127.0.0.1",
                "id": 2797172,
                "detail_uri": "https://api.friendbuy.com/v1/shares/2797172"
            }
        ],
        "id": "402820419",
        "account_id": "402820419"
        "detail_uri": "https://api.friendbuy.com/v1/customers/14681023"
    },
    "trackable_link": "http://fbuy.me/reN"
}

And a example response for shares follows:

{
    "referral_code": "tE",
    "type": "share",
    "campaign": {
        "id": 39805,
        "name": "Spring Collection Offer",
        "published": true,
        "referral_incentive": {
            "type": "shopper_fixed_revenue",
            "value": "10.00"
        },
        "created_at": "2013-03-05T12:15:57.000135-08:00"
    },
    "share": {
        "created_at": "2013-04-18T10:34:30.951885+02:00",
        "referral_code": "dCOYe",
        "ip_address": "8.8.8.8",
        "message": "I love these shoes and so will you",
        "network": "facebook",
        "purchase": {"order_id": "8463164191", "total": "255.99"},
        "sharer": {
            "birthdate": "1952-10-07",
            "customer": {
        "first_name": "Jane",
        "last_name": "Doe",
        "recent_referral_codes": [
            {
                "referral_code": "cuIFR",
                "trackable_link": "http://fbuy.me/cuIFR",
                "destination_url": "http://friendbuy.com"
            },
            {
                "referral_code": "cuyO2",
                "trackable_link": "http://fbuy.me/cuyO2",
                "destination_url": "http://friendbuy.com"
            },
            {
                "referral_code": "cao1",
                "trackable_link": "http://fbuy.me/caock",
                "destination_url": "http://friendbuy.com"
            }
        ],
        "created_at": "2015-03-24T17:33:57.693976",
        "email": "test@example.org",
        "recent_shares": [
            {
                "campaign": {
                    "id": 2544,
                    "name": "Fall sale",
                    "published": true,
                    "referral_incentive": {
                        "type": "shopper_fixed_revenue",
                        "value": "10.00"
                    },
                    "created_at": "2014-07-25T13:59:52.328016-07:00"
                },
                "created_at": "2015-06-09T17:45:26.164477-07:00",
                "sharer": {
                    "customer": {
                        "first_name": "Jane",
                        "last_name": "Doe",
                        "id": "402820419",
                        "detail_uri": "https://api.friendbuy.com/v1/customers/14681023",
                        "email": "test@example.org"
                    },
                    "facebook_friends_count": 0,
                    "twitter_followers_count": 0,
                    "name": "Jane Doe",
                    "email": "test@example.org"
                },
                "email": "test@example.org",
                "message": {
                    "content": "Check it out!",
                    "network": "email"
                },
                "ip_address": "127.0.0.1",
                "id": 3084914,
                "detail_uri": "https://api.friendbuy.com/v1/shares/3084914"
            },
            {
                "campaign": {
                    "id": 2544,
                    "name": "Fall sale",
                    "published": true,
                    "referral_incentive": {
                        "type": "shopper_fixed_revenue",
                        "value": "10.00"
                    },
                    "created_at": "2014-07-25T13:59:52.328016-07:00"
                },
                "created_at": "2015-06-09T17:45:26.164477-07:00",
                "sharer": {
                    "customer": {
                        "first_name": "Jane",
                        "last_name": "Doe",
                        "account_id": "402820419"
                        "id": 14681023,
                        "detail_uri": "https://api.friendbuy.com/v1/customers/14681023",
                        "email": "test@example.org"
                    },
                    "facebook_friends_count": 0,
                    "twitter_followers_count": 0,
                    "name": "",
                    "email": "test@example.org"
                },
                "email": "test@example.org",
                "message": {
                    "content": "You should try this.",
                    "network": "email"
                },
                "ip_address": "127.0.0.1",
                "id": 2797183,
                "detail_uri": "https://api.friendbuy.com/v1/shares/2797183"
            },
            {
                "campaign": {
                    "id": 2544,
                    "name": "Fall sale",
                    "published": true,
                    "referral_incentive": {
                        "type": "shopper_fixed_revenue",
                        "value": "10.00"
                    },
                    "created_at": "2014-07-25T13:59:52.328016-07:00"
                },
                "created_at": "2015-06-09T17:45:26.164477-07:00",
                "sharer": {
                    "customer": {
                        "first_name": "Jane",
                        "last_name": "Doe",
                        "account_id": "402820419"
                        "id": 14681023,
                        "detail_uri": "https://api.friendbuy.com/v1/customers/14681023",
                        "email": "test@example.org"
                    },
                    "facebook_friends_count": 0,
                    "twitter_followers_count": 0,
                    "name": "Jane Doe",
                    "email": "test@example.org"
                },
                "email": "test@example.org",
                "message": {
                    "content": "You might like this.",
                    "network": "email"
                },
                "ip_address": "127.0.0.1",
                "id": 2797172,
                "detail_uri": "https://api.friendbuy.com/v1/shares/2797172"
            }
        ],
        "id": "402820419",
        "account_id": "402820419",
        "detail_uri": "https://api.friendbuy.com/v1/customers/14681023"
    },
            "email": "jane@example.com",
            "facebook_friends_count": 139328,
            "name": "Jane Doe",
            "twitter_followers_count": 1420
        },
        "campaign": {
            "id": 39805,
            "name": "Spring Collection Offer",
            "published": true,
            "referral_incentive": {
                "type": "shopper_fixed_revenue",
                "value": "10.00"
            },
            "created_at": "2013-03-05T12:15:57.000135-08:00"
        }
    },
    "customer": {
        "first_name": "Jane",
        "last_name": "Doe",
        "recent_referral_codes": [
            {
                "referral_code": "cuIFR",
                "trackable_link": "http://fbuy.me/cuIFR",
                "destination_url": "http://friendbuy.com"
            },
            {
                "referral_code": "cuyO2",
                "trackable_link": "http://fbuy.me/cuyO2",
                "destination_url": "http://friendbuy.com"
            },
            {
                "referral_code": "cao1",
                "trackable_link": "http://fbuy.me/caock",
                "destination_url": "http://friendbuy.com"
            }
        ],
        "created_at": "2015-03-24T17:33:57.693976",
        "email": "test@example.org",
        "recent_shares": [
            {
                "campaign": {
                    "id": 2544,
                    "name": "Fall sale",
                    "published": true,
                    "referral_incentive": {
                        "type": "shopper_fixed_revenue",
                        "value": "10.00"
                    },
                    "created_at": "2014-07-25T13:59:52.328016-07:00"
                },
                "created_at": "2015-06-09T17:45:26.164477-07:00",
                "sharer": {
                    "customer": {
                        "first_name": "Jane",
                        "last_name": "Doe",
                        "id": "402820419",
                        "account_id": "402820419"
                        "detail_uri": "https://api.friendbuy.com/v1/customers/14681023",
                        "email": "test@example.org"
                    },
                    "facebook_friends_count": 0,
                    "twitter_followers_count": 0,
                    "name": "Jane Doe",
                    "email": "test@example.org"
                },
                "email": "test@example.org",
                "message": {
                    "content": "Check it out!",
                    "network": "email"
                },
                "ip_address": "127.0.0.1",
                "id": 3084914,
                "detail_uri": "https://api.friendbuy.com/v1/shares/3084914"
            },
            {
                "campaign": {
                    "id": 2544,
                    "name": "Fall sale",
                    "published": true,
                    "referral_incentive": {
                        "type": "shopper_fixed_revenue",
                        "value": "10.00"
                    },
                    "created_at": "2014-07-25T13:59:52.328016-07:00"
                },
                "created_at": "2015-06-09T17:45:26.164477-07:00",
                "sharer": {
                    "customer": {
                        "first_name": "Jane",
                        "last_name": "Doe",
                        "account_id": "402820419"
                        "id": "402820419",
                        "detail_uri": "https://api.friendbuy.com/v1/customers/14681023",
                        "email": "test@example.org"
                    },
                    "facebook_friends_count": 0,
                    "twitter_followers_count": 0,
                    "name": "",
                    "email": "test@example.org"
                },
                "email": "test@example.org",
                "message": {
                    "content": "You should try this.",
                    "network": "email"
                },
                "ip_address": "127.0.0.1",
                "id": 2797183,
                "detail_uri": "https://api.friendbuy.com/v1/shares/2797183"
            },
            {
                "campaign": {
                    "id": 2544,
                    "name": "Fall sale",
                    "published": true,
                    "referral_incentive": {
                        "type": "shopper_fixed_revenue",
                        "value": "10.00"
                    },
                    "created_at": "2014-07-25T13:59:52.328016-07:00"
                },
                "created_at": "2015-06-09T17:45:26.164477-07:00",
                "sharer": {
                    "customer": {
                        "first_name": "Jane",
                        "last_name": "Doe",
                        "account_id": "402820419",
                        "id": "402820419",
                        "detail_uri": "https://api.friendbuy.com/v1/customers/14681023",
                        "email": "test@example.org"
                    },
                    "facebook_friends_count": 0,
                    "twitter_followers_count": 0,
                    "name": "Jane Doe",
                    "email": "test@example.org"
                },
                "email": "test@example.org",
                "message": {
                    "content": "You might like this.",
                    "network": "email"
                },
                "ip_address": "127.0.0.1",
                "id": 2797172,
                "detail_uri": "https://api.friendbuy.com/v1/shares/2797172"
            }
        ],
        "account_id": "402820419",
        "id": 14681023,
        "detail_uri": "https://api.friendbuy.com/v1/customers/14681023"
    },
    "trackable_link": "http://fbuy.me/tE"
}
GET /referral_codes/{code}

Retrieves referral code information from the given code, including the associated share or personal URL. The response JSON, if the request is successful, will be identical to the responses from POST /referral_codes above.

Please Note:
The structure of the response will be different for share referral codes and personal url referral codes. Please see the above examples.

PATCH /referral_codes/{code}

Updates custom parameters associated with the given code. Submit an HTTP PATCH with a body containing JSON as in the following example.

{
    "parameters": {
        "offercode": "BAZ-INGA"
    }
}
GET /customers

Retrieves a list of customers, optionally restricted by account id, email, or those created within a given date range. The id field and account_id field are both currently the same value, the account ID you provided us for the customer. However, in future updates, ID will be replaced by Friendbuy's customer ID. Please use account_id to ensure that your integration will support future API versions. The result contains an array of basic customer data, having the form:

{
    "this_page_results_count": 19,
    "results": [
        {
            "first_name": "John",
            "last_name": "Smith",
            "account_id": "372377336"
            "id": "372377336",
            "detail_uri": "https://api.friendbuy.com/v1/customers/13994497",
            "email": "test@example.org"
        },
        ...
    ],
    "total_results_count": 19,
    "offset": 0
}
GET /customers/{id}

Retrieves details on a single customer, including the 5 most recent shares and referral codes. The URI for a customer detail is obtained from the detail_uri attribute contained in a customer search result. The response has the form:

{
    "first_name": 'John',
    "last_name": 'Smith',
    "recent_referral_codes": [
        {
            "referral_code": "rEN",
            "trackable_link": "http://fbuy.me/rEN",
            "destination_url": "http:/friendbuy.com"
        }
    ],
    "created_at": "2014-09-02T15:05:58.842355",
    "email": 'test@example.org',
    "recent_shares": [
        {
            "campaign": {
                "created_at": "2014-08-05T14:03:34.835177-07:00",
                "referral_incentive": {
                    "type": "reward_amount",
                    "value": "10.00"
                },
                "published": true,
                "id": 9699,
                "name": "My First Referral Campaign"
            },
            "created_at": "2014-09-02T15:07:14.323568-07:00",
            "sharer": {
                "customer": {
                    "first_name": 'John',
                    "last_name": 'Smith',
                    "account_id": "95287",
                    "id": "95287",
                    "detail_uri": "https://api.friendbuy.com/v1/customers/6212657",
                    "email": 'test@example.org'
                },
                "facebook_friends_count": 0,
                "twitter_followers_count": 0,
                "name": "John Smith",
                "email": "test@example.org"
            },
            "email": "test@example.org",
            "message": {
                "content": "Suggested copy placed here.",
                "network": "email"
            },
            "ip_address": "127.0.0.1",
            "id": 1957413,
            "detail_uri": "https://api.friendbuy.com/v1/shares/1957413"
        }
    ],
    "account_id": "95287",
    "id": "95287",
    "detail_uri": "https://api.friendbuy.com/v1/customers/6212657"
}
GET /customers/{id}/shares

Retrieves the shares made by a particular customer, optionally filtered by date range. The URI for a customer detail is obtained from the detail_uri attribute contained in a customer search result. The response has the form:

{
    "this_page_results_count": 20,
    "results": [
        {
            "campaign": {
                "created_at": "2014-08-05T14:03:34.835177-07:00",
                "referral_incentive": {
                    "type": "reward_amount",
                    "value": "10.00"
                },
                "published": true,
                "id": 9699,
                "name": "My First Referral Campaign"
            },
            "created_at": "2014-09-02T15:07:14.323568-07:00",
            "sharer": {
                "customer": {
                    "first_name": 'John',
                    "last_name": 'Smith',
                    "account_id": "95287",
                    "id": "95287",
                    "detail_uri": "https://api.friendbuy.com/v1/customers/6212657",
                    "email": 'test@example.org'
                },
                "facebook_friends_count": 0,
                "twitter_followers_count": 0,
                "name": "",
                "email": "test@example.org"
            },
            "email": "test@example.org",
            "message": {
                "content": "Check this out!",
                "network": "email"
            },
            "ip_address": "127.0.0.1",
            "id": 1957413,
            "detail_uri": "https://api.friendbuy.com/v1/shares/1957413"
        },
        ...
    ],
    "total_results_count": 20,
    "offset": 0
}
GET /customers/{id}/referral_codes

Retrieves the referral codes for a particular customer, optionally filtered by date range. The URI for a customer detail is obtained from the detail_uri attribute contained in a customer search result. The response has the form:

{
    "this_page_results_count": 5,
    "results": [
        {
            "referral_code": "rEN",
            "trackable_link": "http://fbuy.me/rEN",
            "destination_url": "http://friendbuy.com"
        },
        ...
    ],
    "total_results_count": 5,
    "offset": 0
}
GET /customers/{id}/email-recipients

Retrieves a summary of the individuals a particular customer has referred by email. The URI for a customer resource is obtained from the detail_uri in a /customers response result. The invitation_dates list all times at which a specific e-mail address has been referred by the customer. The response has the form:

{
  "offset": 0,
  "results": [
    {
      "email": ""referred.friend1@example.com",
      "invitation_dates": [
        "2016-03-22T22:15:06.207947",
        "2016-03-30T22:00:03.254547",
        "2016-03-30T22:36:57.221404"
      ]
    },
    {
      "email": ""referred.friend2@example.com",
      "invitation_dates": [
        "2016-03-30T23:08:14.747537"
      ]
    }
  ],
  "this_page_results_count": 2,
  "total_results_count": 2
}
Error Responses Description
403 Forbidden You will encounter this status if your account has not been enabled for referral email rights. Please contact your Friendbuy sales representative to inquire about access.
GET /customers/{id}/conversions

Retrieves the conversions associated with a particular customer, optionally filtered by date range. The URI for a customer detail is obtained from the detail_uri attribute contained in a customer search result. The response has the form:

{
    "this_page_results_count": 17,
    "results": [
        {
            "status": "unmarked",
            "rewards": [
                {
                    "status": "valid",
                    "rejected_reasons": null,
                    "amount": "10.00",
                    "id": 338884,
                    "created_at": "2015-05-25T21:42:05.393465-07:00"
                }
            ],
            "campaign": {
                "created_at": "2015-05-25T21:24:56.386418-07:00",
                "referral_incentive": {
                    "type": "reward_amount",
                    "value": "10.00"
                },
                "published": true,
                "id": 15860,
                "name": "Untitled Widget"
            },
            "id": 384438,
            "personal_url": {
                "referral_code": "rEN",
                "trackable_link": "http://fbuy.me/rEN",
                "destination_url": "http://friendbuy.com"
            },
            "possible_self_referral": false,
            "purchase": {
                "order_id": "4",
                "new_customer": "yes",
                "products": [
                    {
                        "sku": "TEST",
                        "price": "10.00",
                        "quantity": "1"
                    }
                ],
                "date": "2015-05-25T21:42:05.332971",
                "total": "10.00",
                "ip_address": "127.0.0.1",
                "email": "test@example.org"
            },
            "fraud": {
                "same_customer": false,
                "same_email": false,
                "fuzzy_email": false,
                "same_shopper": false
            },
            "referrer": {
                "customer": {
                    "first_name": 'John',
                    "last_name": 'Smith',
                    "account_id": "321680519"
                    "id": "321680519",
                    "detail_uri": "https://api.friendbuy.com/v1/customers/7856633",
                    "email": 'test@example.org'
                }
            },
            "created_at": "2015-05-25T21:42:05.332971-07:00",
            "detail_uri": "https://api.friendbuy.com/v1/conversions/384438",
            "reward": null
        },
        ...
    ],
    "total_results_count": 17,
    "offset": 0
}
GET /customers/{id}/rewards

Retrieves the rewards associated with a particular customer including data for the share or personal URL (pURL), campaign and conversion that generated each reward. The results are optionally filtered by date range. The ID for a customer is obtained from the detail_uri attribute contained in a customer search result. The response has the form:

{
  "offset": 0,
  "results": [
    {
      "amount": "5.00",
      "conversion": {
        "campaign": {
          "created_at": "2016-03-22T20:05:45.074247-07:00",
          "id": 333477,
          "name": "Untitled Widget",
          "published": true,
          "referral_incentive": {
            "type": "reward_amount",
            "value": "5.00"
          }
        },
        "created_at": "2016-04-13T16:21:26.424652-07:00",
        "detail_uri": "https://api.friendbuy.com/v1/conversions/47294",
        "fraud": {
          "fuzzy_email": true,
          "same_customer": false,
          "same_email": false,
          "same_shopper": false
        },
        "id": 47294,
        "possible_self_referral": false,
        "purchase": {
          "date": "2016-04-13T16:21:26.424652",
          "email": "friend@gmail.com",
          "ip_address": "127.0.0.1",
          "new_customer": "yes",
          "order_id": "26325Z",
          "products": [],
          "total": "1337.00"
        },
        "referrer": {
          "customer": {
            "account_id": "4320948",
            "detail_uri": "https://api.friendbuy.com/v1/customers/19486",
            "email": "referrer@gmail.com",
            "first_name": null,
            "id": "4320948",
            "last_name": null
          },
          "email": "referrer@gmail.com",
          "facebook_friends_count": 0,
          "name": "",
          "twitter_followers_count": 0
        },
        "reward": null,
        "share": {
          "campaign": {
            "created_at": "2016-03-22T20:05:45.074247-07:00",
            "id": 333477,
            "name": "Awesome Widget",
            "published": true,
            "referral_incentive": {
              "type": "reward_amount",
              "value": "5.00"
            }
          },
          "created_at": "2016-04-13T16:19:37.972390-07:00",
          "detail_uri": "https://api.friendbuy.com/v1/shares/139986",
          "id": 139986,
          "ip_address": "127.0.0.1",
          "message": {
            "content": "Check this out!",
            "network": "email"
          },
          "email_recipients": ["friend@gmail.com"],
          "referral_code": "QMi",
          "sharer": {
            "customer": {
              "account_id": "h3242093r",
              "detail_uri": "https://api.friendbuy.com/v1/customers/19486",
              "email": "sharer@gmail.com",
              "first_name": null,
              "id": "h3242093r",
              "last_name": null
            },
            "email": "sharer@gmail.com",
            "facebook_friends_count": 0,
            "name": "",
            "twitter_followers_count": 0
          }
        },
        "status": "unmarked"
      },
      "created_at": "2016-04-13T16:21:27.137658-07:00",
      "evaluate_at": null,
      "id": 16501,
      "rejected_reasons": null,
      "status": "valid",
      "type": "fixed_cash"
    }
  ],
  "this_page_results_count": 1,
  "total_results_count": 1
}
GET /opt_outs/emails

Retrieves the emails that have opted out of communication, optionally filtered by date range.

{
  "offset": 0,
  "results": [
    {
      "created_at": "2015-10-12T15:21:41.974304-07:00",
      "email": "bad3@example.com",
      "id": 10899,
      "ip_address": "None",
      "source": "upload"
    },
    {
      "created_at": "2015-10-12T15:19:05.470994-07:00",
      "email": "bad2@example.com",
      "id": 10898,
      "ip_address": "None",
      "source": "upload"
    },
    {
      "created_at": "2015-10-12T15:17:18.479865-07:00",
      "email": "bad@example.com",
      "id": 10897,
      "ip_address": "None",
      "source": "upload"
    }
  ],
  "this_page_results_count": 3,
  "total_results_count": 3
}
POST /opt_outs/emails

Adds a list of emails to your email opt out list. Post a JSON document in your request as in the following example.

{
  "emails": [
    "bad@example.org",
    "also_bad@example.org"
  ]
}

The response will contain a message and an update_id that can be used to check on the status of the upload.

{
  "message": "Processing 1 emails to the opt out list",
  "update_id": 531
}
GET /opt_outs/email_update/{id}

Check the status of an email opt out request. The id used here is the update_id returned in the response to POST calls to /opt_outs/emails

{
  "created_at": "2015-10-12T15:21:40.186590",
  "failure_reason": null,
  "filename": null,
  "id": 530,
  "last_modified_at": "2015-10-12T15:21:40.186590",
  "status": "Success",
  "total_items_count": 1,
  "updated_items_count": 1
}

Examples

Example Curl Calls

Create a new purchase with the ref code "ABCD", customer "1234", no products, and an order totaling $0 with an id of "9999."
curl -XPOST \
  -H "Content-Type: application/json" \
  -d '{"referral_code": "ABCD", "customer": { "id": "1234"},
        "products": [], "order": {"amount": 0, "id": "9999", "email": "email@example.org", "new_customer": true}}' \
  https://API_USERNAME:API_PASSWORD@api.friendbuy.com/v1/purchases
                                    
Retrieve the information associated with the referral code "ABCD"
curl -XGET \
https://API_USERNAME:API_PASSWORD@api.friendbuy.com/v1/referral_codes/ABCD
                                    

Usage Examples

Export a list of users who’ve shared in the last 30 days so I can reach out and encourage them to share again, or just to say "thanks for sharing!"
GET /shares?from_date=2014-09-18

(substitute whichever date is 30 days prior to today, or any cutoff date of your choice)

  • Parse the JSON response into an array of share objects.
  • For each share object, examine the sharer property to see the user that generated the share.
  • You can create a set of these user objects (via set() in Python, .uniq in Ruby, or new HashSet() in Java) if desired.
  • Note that user objects already contain name and email fields, so there is no need for additional API requests.
Show me users who have generated a referral conversion during March of 2014 so I can follow up and say "thanks!" or ask them to refer again.
GET /conversions?from_date=2014-03-01&to_date=2014-03-31
  • Parse the JSON response into an array of conversion objects.
  • For each conversion object, examine the referrer property to see the user that nerated the conversion.
  • You can create a set of these user objects (via set() iPython, .uniq in Ruby, or new HashSet() in Java) if desired.
  • Note that user objects already contain name and email fields, so there is no need for additional API requests.