friendbuy | Developer Docs
Navbar
  • Introduction
  • REST API v2
  • Webhooks
  • Client API Integrations
  • Embedded JavaScript
  • Introduction

    Welcome to our developer documentation! Here you will find complete reference information for each of Friendbuy’s integration methods.

    You will find JSON and JavaScript code examples in the right-hand pane and explanations of parameters and data models in the center pane.

    You can also visit our Help Center for end user documentation.

    Integration Methods

    Friendbuy offers several integration options for your applications:

    Content Types

    The content type for all requests and responses for the REST API, webhooks, and client integrations is application/json.

    Response Codes

    Each request to the REST API will return one or more of the following codes in the HTTP response, to indicate success or failure:

    Code Meaning Description
    200 OK The request was successful and the response body contains valid data
    201 Created An entity was successfully created
    202 Accepted The request for an asynchronous operation was received
    400 Bad Request The request was malformed or semantically invalid
    401 Unauthorized The request did not contain proper credentials
    404 Not Found The requested resource could not be found
    405 Method Not Allowed The endpoint does not permit access via the specified method
    406 Not Acceptable The request asked for a response in a format other than JSON
    409 Conflict The request attempted to create a resource with a key that already exits
    410 Gone The endpoint is no longer supported
    503 Service Unavailable The API is temporarily offline

    For webhooks and client integrations, the response codes expected from your servers are:

    Code Description
    200 The request was successful and the response body contains valid data
    non-200 The webhook or integration request failed

    Retries

    If the response from a webhook or integration call is not 200, Friendbuy will retry the same request once per hour for at most 24 hours, or until a 200 respsonse is received.

    Whitelisting

    Webhook and client API calls to your endpoints will originate from the following IP addresses:

    REST API v2

    The REST API provides the ability to programmatically create and retrieve data associated with a referral program and supports integration use cases such as:

    Each endpoint available through the REST API is documented below. For each endpoint, a complete technical specification of the supported query parameters, request body, and the response data model appears in the center pane. The right-hand pane contains an Example tab for easily viewing sample JSON responses.

    Security

    Your Friendbuy account comes with an access key and a secret key. Use these keys in the POST tokens/merchant endpoint to receive a long-lived token for accessing the other REST API endpoints from your server. You can also use the POST tokens/customer endpoint to obtain a very short-lived token, scoped to one of your customers, to allow certain API calls directly from a client device. Every REST API endpoint except POST tokens/merchant requires a merchant or customer token in the Authorization header.

    Base URL

    The Base URL of all REST API endpoints is https://api.friendbuy.com/v2.

    The Sandbox

    A Try It button is available for all endpoints. This feature simulates a working API integration where you can experiment with POST, PATCH, and GET calls, and receive associated responses. The Base URL for sandbox API endpoints is https://developer-api.friendbuy.com/v2.

    The Try It feature makes use of a sandboxed database that is pre-populated with sample data. Data can be added to the sandbox by using Try It for a POST or PATCH call, such as POST /purchases. The database is reset to baseline sample data every 30 minutes, so feel free to experiment.

    The sandbox contains the following sample entities:

    Entity Type Values
    Campaigns ids 1...4
    Customers internal ids 1...3; account ids JAYZ, ALCP, and MNLS, respectively
    Referral Codes cP4...cP9, cP-, q5A...q5H, uxB...uxE, uxQ...uxS
    Shares ids 1..5 and 7..9
    Reminder emails id 14
    Purchases ids 1..6
    Conversions ids 1...8
    Rewards ids 1...8
    Coupon Codes SPECIAL1000...SPECIAL1004
    Email Opt Out Addresses 5 of them
    Email Opt Out Job Statuses ids 1..5

    Once the Try it button is clicked, the response from the sandbox is displayed in the Try It tab in the right-hand pane.

    Response Wrapper

    // EXAMPLE ERROR RESPONSE
    {
      "errors": [
        "Limit parameter must be a positive integer"
      ]
    }
    

    Each API response has one of three forms.

    Tokens

    The REST API provides two types of tokens for authentication and authorization:
    (1) a merchant token, which is long-lived and should be stored securely on your server
    (2) a customer token which is short-lived (10 minutes) and can be used by requests originating from your customer’s devices (mobile apps)

    POST /tokens/merchant

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "token": "34895C7hf30BYV0u9geyuFYUEG75Cq9457"
    }
    
    // To see live output, click the Try It button
    

    Creates a merchant token for use in making API calls from your server. This is the only unauthenticated endpoint in the API.

    Body Parameters

    access_key*
    Your access key (use 45d31101-eec0-42d3-8e17-b580c7685642 for this sandbox)
    secret_key*
    Your secret key (use 23355bf4-5f6a-4d2e-a774-0055c45a828b for this sandbox)

    * Required field

    Response Model

    MerchantToken
    token
    string
    A very long-lived merchant token, to be used in all subsequent requests from your server

    DELETE /tokens/merchant

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "success": "true"
    }
    
    // To see live output, click the Try It button
    

    Invalidates all outstanding merchant tokens.

    Body Parameters

    access_key*
    Your access key (use 45d31101-eec0-42d3-8e17-b580c7685642 for this sandbox)
    secret_key*
    Your secret key (use 23355bf4-5f6a-4d2e-a774-0055c45a828b for this sandbox)

    * Required field

    Response Model

    Confirmation
    success
    boolean
    An indication of whether or not the requested operation succeeded.

    POST /tokens/customer

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "token": "34895C7hf30BYV0u939xmIsG75Cq9457"
    }
    
    // To see live output, click the Try It button
    

    Creates a customer token for use in making API calls from a device owned by one of your customers. The token will ensure all requests are scoped to that customer. The token is short-lived, expiring 10 minutes from issue time.

    Endpoints that can be used with a Customer Token:
    POST /personal_referral_links
    GET /personal_referral_links
    POST /shares
    GET /shares
    GET /conversions
    GET /rewards
    GET /coupons

    Body Parameters

    customer_id*
    The id generated by and used internally by Friendbuy for your customer (not the same as the account id assigned to the customer by you). This can be obtained from your id by invoking GET /customers?account_id=

    * Required field

    Response Model

    CustomerToken
    token
    string
    A very short-lived customer token, able to be used directly from a client device

    Widgets

    Widgets are one of the primary mechanisms used to generate referrals. Widgets that belong to the same widget group for purposes such as A-B testing are known as variants of each other. Each widget variant is assigned its own widget id. For more information on widgets, widget variants, and widget groups, see the section Referral & Sharing → Widgets in the Friendbuy application.

    GET /widgets

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "next_page": "https://developer-api.friendbuy.com/v2/widgets?cursor=70",
      "results_count": 20,
      "results": [
        {
          "id": 78,
          "widget_group_id": "hm-NNz",
          "name": "Fall Shoe Sale",
          "objective": "referral",
          "distribution": 50,
          "published": true,
          "active": true,
          "reward_type": "fixed_cash",
          "reward_amount": 25,
          "created_at": "2017-01-13T19:18:38.239Z",
          "last_modified_at": "2017-01-13T19:18:38.239Z"
        }
      ]
    }
    
    // To see live output, click the Try It button
    

    Retrieves a list of widget variants.

    Query Parameters

    cursor
    Value for pagination, obtained from the response of the previous page. Omitted when requesting the first page of results
    limit
    Maximum number of results to return for the page
    from
    First date of range (YYYY-MM-DD, inclusive)
    to
    Last date of range (YYYY-MM-DD, inclusive)
    widget_group_id
    The widget group to search within
    name
    Name of the widget

    Response Model

    Widget
    id
    integer
    Friendbuy-assigned id for the widget variant
    widget_group_id
    string
    Identifier denoting the group (of widget variants) to which the widget belongs
    name
    string
    Name of the widget
    objective
    string
    One of referral, email_capture, or influencer
    distribution
    integer
    Percentage chance that the widget’s widget will be served (100 for widgets that have no variants)
    published
    boolean
    Whether the widget has been published
    active
    boolean
    Whether the widget is active
    reward_type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    reward_amount
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    GET /widgets/{id}

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "widget": {
        "id": 78,
        "widget_group_id": "hm-NNz",
        "name": "Fall Shoe Sale",
        "objective": "referral",
        "distribution": 50,
        "published": true,
        "active": true,
        "reward_type": "fixed_cash",
        "reward_amount": 25,
        "created_at": "2017-01-13T19:18:38.239Z",
        "last_modified_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    Retrieves the widget variant with the given widget variant id.

    Path Parameters

    id*
    Can be located on the Widget Installation Code tab within a widget management page, or via GET/widgets endpoint

    *Required field

    Response Model

    Widget
    id
    integer
    Friendbuy-assigned id for the widget variant
    widget_group_id
    string
    Identifier denoting the group (of widget variants) to which the widget belongs
    name
    string
    Name of the widget
    objective
    string
    One of referral, email_capture, or influencer
    distribution
    integer
    Percentage chance that the widget’s widget will be served (100 for widgets that have no variants)
    published
    boolean
    Whether the widget has been published
    active
    boolean
    Whether the widget is active
    reward_type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    reward_amount
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    Customers

    For a more seamless integration of your referral program with Friendbuy, information about your logged in customers—including their account id, email address, and name—can be passed to us. This can be done at through a Track Customer call via the Friendbuy JavaScript embedded on your site, or via the POST /customers endpoint. A new customer record will be created by Friendbuy each time a unique customer account id is passed to us.

    Customer data stored in Friendbuy can be leveraged to auto-populate widget fields, as well as tie referral activity to specific users as they are defined in your system.

    POST /customers

    • Example
    • Try It
    // Example Response (201 CREATED OR 200 OK)
    {
      "customer": {
        "id": "8307",
        "account_id": "JAYZ",
        "email_address": "jzheng@example.mil",
        "first_name": "Jaylene",
        "last_name": "Zheng",
        "stripe_customer_id": "cus_Agg4bCEhno7A1E",
        "chargebee_customer_id": "4gkYnd21ouvW",
        "first_purchase_date": "2017-02-01T01:31:10.949Z",
        "last_purchase_date": "2017-02-01T01:31:10.949Z",
        "created_at": "2017-01-13T19:18:38.239Z",
        "last_modified_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    Creates or updates a customer record within Friendbuy. Use the returned customer id when associating this customer with shares, purchases, rewards, etc.

    If the account_id has not been seen before, Friendbuy will create a new customer record in our system. If it has, we will update our customer record with the data supplied in the request.

    Body Parameters

    account_id*
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    email_address
    Email associated with the customer
    first_name
    Customer first name
    last_name
    Customer last name
    stripe_customer_id
    Stripe’s id for the customer
    chargebee_customer_id
    Chargebee’s id for the customer

    * Required field

    Response Model

    Customer
    id
    integer
    The id generated by and used internally by Friendbuy for your customer (not the same as the account id assigned to the customer by you)
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    first_purchase_date
    datetime
    Timestamp of the customer’s first recorded purchase
    last_purchase_date
    datetime
    Timestamp of the customer’s most recent recorded purchase
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    GET /customers

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "next_page": "https://developer-api.friendbuy.com/v2/customers?cursor=70",
      "results_count": 20,
      "results": [
        {
          "id": "8307",
          "account_id": "JAYZ",
          "email_address": "jzheng@example.mil",
          "first_name": "Jaylene",
          "last_name": "Zheng",
          "stripe_customer_id": "cus_Agg4bCEhno7A1E",
          "chargebee_customer_id": "4gkYnd21ouvW",
          "first_purchase_date": "2017-02-01T01:31:10.949Z",
          "last_purchase_date": "2017-02-01T01:31:10.949Z",
          "created_at": "2017-01-13T19:18:38.239Z",
          "last_modified_at": "2017-01-13T19:18:38.239Z"
        }
      ]
    }
    
    // To see live output, click the Try It button
    

    Retrieves a list of customers.

    Query Parameters

    cursor
    Value for pagination, obtained from the response of the previous page. Omitted when requesting the first page of results
    limit
    Maximum number of results to return for the page
    from
    First date of range (YYYY-MM-DD, inclusive)
    to
    Last date of range (YYYY-MM-DD, inclusive)
    account_id
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    name
    Leading characters of the first or last name, for a case-insensitive search

    Response Model

    Customer
    id
    integer
    The id generated by and used internally by Friendbuy for your customer (not the same as the account id assigned to the customer by you)
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    first_purchase_date
    datetime
    Timestamp of the customer’s first recorded purchase
    last_purchase_date
    datetime
    Timestamp of the customer’s most recent recorded purchase
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    GET /customers/{id}

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "customer": {
        "id": "8307",
        "account_id": "JAYZ",
        "email_address": "jzheng@example.mil",
        "first_name": "Jaylene",
        "last_name": "Zheng",
        "stripe_customer_id": "cus_Agg4bCEhno7A1E",
        "chargebee_customer_id": "4gkYnd21ouvW",
        "first_purchase_date": "2017-02-01T01:31:10.949Z",
        "last_purchase_date": "2017-02-01T01:31:10.949Z",
        "created_at": "2017-01-13T19:18:38.239Z",
        "last_modified_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    Retrieves the customer with the given Friendbuy id. See the description below for instructions on retrieving this id.

    Path Parameters

    id*
    The id generated by and used internally by Friendbuy for your customer (not the same as the account id assigned to the customer by you). This can be obtained from your id by invoking GET /customers?account_id=

    *Required field

    Response Model

    Customer
    id
    integer
    The id generated by and used internally by Friendbuy for your customer (not the same as the account id assigned to the customer by you)
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    first_purchase_date
    datetime
    Timestamp of the customer’s first recorded purchase
    last_purchase_date
    datetime
    Timestamp of the customer’s most recent recorded purchase
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    Referrals are tracked using a Friendbuy-generated identifier called a referral code (e.g. b7x). These short strings are bound to a particular widget variant, an advocate, and and associated referral method (widget share, reminder email, PURL) to create a referral link. Referral links give Friendbuy the ability to track clicks, referred purchases, and establish attribution back to an advocate.

    A new referral link is generated for each share made through a referral widget, and for each reminder email you generate. In addition, a personal referral link can be created for a specific advocate-widget combination for the advocate to refer friends via out-of-band channels such as email, telephone, or manual posts to social media accounts.

    POST /personal_referral_links

    • Example
    • Try It
    // Example Request Body
    {
      "widget_id": 4,
      "customer_id": 89,
      "email_address": "morgan@example.com",
      "link_parameters": {
        "utm_medium": "referral",
        "utm_source": "Friendbuy"
      }
    }
    
    // Example Response (201 CREATED)
    {
      "referral_link": {
        "type": "email_personal_url",
        "code": "uxC",
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "origin": "alice@example.org",
        "link_parameters": "{\"utm_medium\": \"referral\", \"utm_source\": \"Friendbuy\"}"
      }
    }
    
    // To see live output, click the Try It button
    

    Generates a referral link for a specific advocate-widget combination.

    If the customer id parameter is supplied, the advocate will be the associated customer and the generated link is called a customer personal url, or customer purl. Otherwise, the advocate is known solely by the given email address and the generated link is called an email personal url, or email purl. There is no functional difference from an advocate or friend perspective between the two types of purls.

    Body Parameters

    widget_id*
    Can be located on the Widget Installation Code tab within a widget management page, or via GET/widgets endpoint
    customer_id**
    The id generated by and used internally by Friendbuy for your customer (not the same as the account id assigned to the customer by you). This can be obtained from your id by invoking GET /customers?account_id=. Supply only if creating or retrieving customer purls
    email_address**
    Email address, if creating or retrieving email purls
    link_parameters
    Link parameters to set on the referral code (enter as JSON to try out)

    * Required field
    ** At least one of these fields is required

    Response Model

    ReferralLink
    type
    string
    One of customer_personal_url or email_personal_url
    code
    string
    Short alphanumeric code (e.g., uxC)
    widget
    string
    API link of the associated widget
    origin
    string
    The customer or email address associated with this link. If the link is a customer purl, this field is the url of the customer. If the link is bound to an email purl, the field is the email address
    link_parameters
    string
    Link parameters set on the referral code
    // Example Response (200 OK)
    {
      "next_page": "https://developer-api.friendbuy.com/v2/referral_links?cursor=70",
      "results_count": 20,
      "results": [
        {
          "type": "email_personal_url",
          "code": "uxC",
          "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
          "origin": "alice@example.org",
          "link_parameters": "{\"utm_medium\": \"referral\", \"utm_source\": \"Friendbuy\"}"
        }
      ]
    }
    
    // To see live output, click the Try It button
    

    Retrieves a list of personal referral links.

    Query Parameters

    Response Model

    ReferralLink
    type
    string
    One of customer_personal_url or email_personal_url
    code
    string
    Short alphanumeric code (e.g., uxC)
    widget
    string
    API link of the associated widget
    origin
    string
    The customer or email address associated with this link. If the link is a customer purl, this field is the url of the customer. If the link is bound to an email purl, the field is the email address
    link_parameters
    string
    Link parameters set on the referral code
    // Example Response (200 OK)
    {
      "referral_link": {
        "type": "email_personal_url",
        "code": "uxC",
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "origin": "alice@example.org",
        "link_parameters": "{\"utm_medium\": \"referral\", \"utm_source\": \"Friendbuy\"}"
      }
    }
    
    // To see live output, click the Try It button
    

    Retrieves the referral link with the given referral code.

    Path Parameters

    *Required field

    Response Model

    ReferralLink
    type
    string
    One of customer_personal_url or email_personal_url
    code
    string
    Short alphanumeric code (e.g., uxC)
    widget
    string
    API link of the associated widget
    origin
    string
    The customer or email address associated with this link. If the link is a customer purl, this field is the url of the customer. If the link is bound to an email purl, the field is the email address
    link_parameters
    string
    Link parameters set on the referral code
    // Example Response (200 OK)
    {
      "referral_link": {
        "type": "email_personal_url",
        "code": "uxC",
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "origin": "alice@example.org",
        "link_parameters": "{\"utm_medium\": \"referral\", \"utm_source\": \"Friendbuy\"}"
      }
    }
    
    // To see live output, click the Try It button
    

    Updates the tracking parameters associated with a specific referral link. Although the most common type of link parameter is the UTM, this endpoint allows you define any key-value pair to be appended to referral link for a PURL.

    Path Parameters

    *Required field

    Body Parameters

    * Required field

    Response Model

    ReferralLink
    type
    string
    One of customer_personal_url or email_personal_url
    code
    string
    Short alphanumeric code (e.g., uxC)
    widget
    string
    API link of the associated widget
    origin
    string
    The customer or email address associated with this link. If the link is a customer purl, this field is the url of the customer. If the link is bound to an email purl, the field is the email address
    link_parameters
    string
    Link parameters set on the referral code

    Shares

    A share occurs when an advocate refers a friend directly through a Friendbuy widget. The share will be associated to a specific channel, such as email, Facebook, or Twitter.

    POST /shares

    • Example
    • Try It
    // Example Request Body
    {
      "widget_id": 4,
      "reward_email_address": "root@fifa.example.org",
      "email_recipients": [
        "pele@example.br",
        "messi@example.ar"
      ],
      "message": "Good game!",
      "newsletter_opt_in": true,
      "send_reminder": true,
      "ip_address": "8.8.8.8",
      "customer_id": 89,
      "link_parameters": {
        "utm_medium": "referral",
        "utm_source": "Friendbuy",
        "referrer": "MDMQ4DE9"
      }
    }
    
    // Example Response (201 CREATED)
    {
      "share": {
        "id": 196418,
        "message": "Check these out",
        "channel": "facebook",
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "ip_address": "8.8.8.8",
        "referral_link": "https://developer-api.friendbuy.com/v2/referral_links/uXc",
        "newsletter_opt_in": true,
        "send_reminder": true,
        "customer": "https://developer-api.friendbuy.com/v2/customers/17",
        "reward_email_address": "alice@example.org",
        "email_recipients": [
          "pele@example.br",
          "messi@example.ar"
        ],
        "link_parameters": "{\"utm_medium\": \"referral\", \"utm_source\": \"Friendbuy\"}",
        "created_at": "2017-01-13T19:18:38.239Z",
        "last_modified_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    Generates a new email share.

    Body Parameters

    widget_id*
    Can be located on the Widget Installation Code tab within a widget management page, or via GET/widgets endpoint
    reward_email_address*
    Email address from which the share is sent
    email_recipients*
    Array of recipients of the share (enter as comma-separated list to try out)
    message
    Message sent with the share
    newsletter_opt_in
    Whether a newsletter opt in should take place with the share
    send_reminder
    Whether a reminder should be sent for the share
    ip_address
    IP address of the share
    customer_id
    The id generated by and used internally by Friendbuy for your customer (not the same as the account id assigned to the customer by you). This can be obtained from your id by invoking GET /customers?account_id=
    link_parameters
    Custom referral parameters, for additional details about shares

    * Required field

    Response Model

    Share
    id
    integer
    Friendbuy internal id for this share
    message
    string
    Message sent along with share
    channel
    string
    One of facebook, twitter, messenger, or email
    widget
    string
    API link of the associated widget
    ip_address
    string
    IP address of the share
    referral_link
    string
    API link of the referral link
    newsletter_opt_in
    boolean
    Whether a newsletter opt in should take place with the share
    send_reminder
    boolean
    Whether a reminder should be sent for the share
    customer
    string
    API link of the associated customer, if any
    reward_email_address
    string
    Email address of the advocate
    email_recipients
    array
    Array of recipients for the share, present only if (1) the share is an email share and (2) the merchant is permitted to access this information (Contact Friendbuy to inquire about the ability to access the recipient list)
    link_parameters
    string
    Link parameters set on the referral code
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    GET /shares

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "next_page": "https://developer-api.friendbuy.com/v2/shares?cursor=70",
      "results_count": 20,
      "results": [
        {
          "id": 196418,
          "message": "Check these out",
          "channel": "facebook",
          "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
          "ip_address": "8.8.8.8",
          "referral_link": "https://developer-api.friendbuy.com/v2/referral_links/uXc",
          "newsletter_opt_in": true,
          "send_reminder": true,
          "customer": "https://developer-api.friendbuy.com/v2/customers/17",
          "reward_email_address": "alice@example.org",
          "email_recipients": [
            "pele@example.br",
            "messi@example.ar"
          ],
          "link_parameters": "{\"utm_medium\": \"referral\", \"utm_source\": \"Friendbuy\"}",
          "created_at": "2017-01-13T19:18:38.239Z",
          "last_modified_at": "2017-01-13T19:18:38.239Z"
        }
      ]
    }
    
    // To see live output, click the Try It button
    

    Retrieves a list of shares.

    Query Parameters

    cursor
    Value for pagination, obtained from the response of the previous page. Omitted when requesting the first page of results
    limit
    Maximum number of results to return for the page
    from
    First date of range (YYYY-MM-DD, inclusive)
    to
    Last date of range (YYYY-MM-DD, inclusive)
    widget_id
    Can be located on the Widget Installation Code tab within a widget management page, or via GET/widgets endpoint
    customer_id
    The id generated by and used internally by Friendbuy for your customer (not the same as the account id assigned to the customer by you). This can be obtained from your id by invoking GET /customers?account_id=
    email_address
    The reward email address for the share

    Response Model

    Share
    id
    integer
    Friendbuy internal id for this share
    message
    string
    Message sent along with share
    channel
    string
    One of facebook, twitter, messenger, or email
    widget
    string
    API link of the associated widget
    ip_address
    string
    IP address of the share
    referral_link
    string
    API link of the referral link
    newsletter_opt_in
    boolean
    Whether a newsletter opt in should take place with the share
    send_reminder
    boolean
    Whether a reminder should be sent for the share
    customer
    string
    API link of the associated customer, if any
    reward_email_address
    string
    Email address of the advocate
    email_recipients
    array
    Array of recipients for the share, present only if (1) the share is an email share and (2) the merchant is permitted to access this information (Contact Friendbuy to inquire about the ability to access the recipient list)
    link_parameters
    string
    Link parameters set on the referral code
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    GET /shares/{id}

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "share": {
        "id": 196418,
        "message": "Check these out",
        "channel": "facebook",
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "ip_address": "8.8.8.8",
        "referral_link": "https://developer-api.friendbuy.com/v2/referral_links/uXc",
        "newsletter_opt_in": true,
        "send_reminder": true,
        "customer": "https://developer-api.friendbuy.com/v2/customers/17",
        "reward_email_address": "alice@example.org",
        "email_recipients": [
          "pele@example.br",
          "messi@example.ar"
        ],
        "link_parameters": "{\"utm_medium\": \"referral\", \"utm_source\": \"Friendbuy\"}",
        "created_at": "2017-01-13T19:18:38.239Z",
        "last_modified_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    Retrieves the share with the given id.

    Path Parameters

    id*
    The internal id of the share

    *Required field

    Response Model

    Share
    id
    integer
    Friendbuy internal id for this share
    message
    string
    Message sent along with share
    channel
    string
    One of facebook, twitter, messenger, or email
    widget
    string
    API link of the associated widget
    ip_address
    string
    IP address of the share
    referral_link
    string
    API link of the referral link
    newsletter_opt_in
    boolean
    Whether a newsletter opt in should take place with the share
    send_reminder
    boolean
    Whether a reminder should be sent for the share
    customer
    string
    API link of the associated customer, if any
    reward_email_address
    string
    Email address of the advocate
    email_recipients
    array
    Array of recipients for the share, present only if (1) the share is an email share and (2) the merchant is permitted to access this information (Contact Friendbuy to inquire about the ability to access the recipient list)
    link_parameters
    string
    Link parameters set on the referral code
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    Reminder Emails

    GET /reminder_emails

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "next_page": "https://developer-api.friendbuy.com/v2/reminder_emails?cursor=70",
      "results_count": 20,
      "results": [
        {
          "id": 377,
          "customer": "https://developer-api.friendbuy.com/v2/customers/17",
          "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
          "share": "https://developer-api.friendbuy.com/v2/shares/93813",
          "referral_link": "https://developer-api.friendbuy.com/v2/referral_links/uXc",
          "advocate_email_address": "jzheng@example.mil",
          "email_recipients_count": 100,
          "created_at": "2017-01-13T19:18:38.239Z",
          "last_modified_at": "2017-01-13T19:18:38.239Z"
        }
      ]
    }
    
    // To see live output, click the Try It button
    

    Retrieves a list of reminder emails.

    Query Parameters

    cursor
    Value for pagination, obtained from the response of the previous page. Omitted when requesting the first page of results
    limit
    Maximum number of results to return for the page
    from
    First date of range (YYYY-MM-DD, inclusive)
    to
    Last date of range (YYYY-MM-DD, inclusive)

    Response Model

    ReminderEmail
    id
    integer
    Friendbuy-assigned id for the reminder email
    customer
    string
    API link of the associated customer, if any
    widget
    string
    API link of the associated widget
    share
    string
    API link of the associated share.
    referral_link
    string
    API link of the referral link
    advocate_email_address
    string
    Email address of the advocate
    email_recipients_count
    integer
    Number of email recipients of the original share
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    GET /reminder_emails/{id}

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "reminder_email": {
        "id": 377,
        "customer": "https://developer-api.friendbuy.com/v2/customers/17",
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "share": "https://developer-api.friendbuy.com/v2/shares/93813",
        "referral_link": "https://developer-api.friendbuy.com/v2/referral_links/uXc",
        "advocate_email_address": "jzheng@example.mil",
        "email_recipients_count": 100,
        "created_at": "2017-01-13T19:18:38.239Z",
        "last_modified_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    Retrieves the reminder email with the given id.

    Path Parameters

    id*
    The internal id of the reminder_email

    *Required field

    Response Model

    ReminderEmail
    id
    integer
    Friendbuy-assigned id for the reminder email
    customer
    string
    API link of the associated customer, if any
    widget
    string
    API link of the associated widget
    share
    string
    API link of the associated share.
    referral_link
    string
    API link of the referral link
    advocate_email_address
    string
    Email address of the advocate
    email_recipients_count
    integer
    Number of email recipients of the original share
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    Email Captures

    POST /email_captures

    • Example
    • Try It
    // Example Request Body
    {
      "widget_id": 4,
      "email_address": "messi@example.ar",
      "newsletter_opt_in": true,
      "referral_code": "uxC",
      "ip_address": "200.1.2.3"
    }
    
    // Example Response (201 CREATED)
    {
      "email_capture": {
        "id": 377,
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "referral_link": "https://developer-api.friendbuy.com/v2/referral_links/uXc",
        "email_address": "jzheng@example.mil",
        "ip_address": "200.1.2.3",
        "created_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    Generates a new email capture.

    Body Parameters

    widget_id*
    Can be located on the Widget Installation Code tab within a widget management page, or via GET/widgets endpoint
    email_address*
    Captured email address
    newsletter_opt_in
    Whether a newsletter opt in should take place with the email capture
    referral_code
    Short alphanumeric code (e.g., uxC)
    ip_address
    IP address associated with the capture

    * Required field

    Response Model

    EmailCapture
    id
    integer
    Friendbuy-assigned id for the email capture
    widget
    string
    API link of the associated widget
    referral_link
    string
    API link of the referral link
    email_address
    string
    The captured email address
    ip_address
    string
    IP address
    created_at
    datetime
    Creation timestamp

    GET /email_captures

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "next_page": "https://developer-api.friendbuy.com/v2/email_captures?cursor=70",
      "results_count": 20,
      "results": [
        {
          "id": 377,
          "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
          "referral_link": "https://developer-api.friendbuy.com/v2/referral_links/uXc",
          "email_address": "jzheng@example.mil",
          "ip_address": "200.1.2.3",
          "created_at": "2017-01-13T19:18:38.239Z"
        }
      ]
    }
    
    // To see live output, click the Try It button
    

    Retrieves a list of email_captures.

    Query Parameters

    cursor
    Value for pagination, obtained from the response of the previous page. Omitted when requesting the first page of results
    limit
    Maximum number of results to return for the page
    from
    First date of range (YYYY-MM-DD, inclusive)
    to
    Last date of range (YYYY-MM-DD, inclusive)
    widget_id
    Can be located on the Widget Installation Code tab within a widget management page, or via GET/widgets endpoint
    email_address
    Email address to filter by

    Response Model

    EmailCapture
    id
    integer
    Friendbuy-assigned id for the email capture
    widget
    string
    API link of the associated widget
    referral_link
    string
    API link of the referral link
    email_address
    string
    The captured email address
    ip_address
    string
    IP address
    created_at
    datetime
    Creation timestamp

    GET /email_captures/{id}

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "email_capture": {
        "id": 377,
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "referral_link": "https://developer-api.friendbuy.com/v2/referral_links/uXc",
        "email_address": "jzheng@example.mil",
        "ip_address": "200.1.2.3",
        "created_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    Retrieves the email capture with the given id.

    Path Parameters

    id*
    The internal id of the email capture

    *Required field

    Response Model

    EmailCapture
    id
    integer
    Friendbuy-assigned id for the email capture
    widget
    string
    API link of the associated widget
    referral_link
    string
    API link of the referral link
    email_address
    string
    The captured email address
    ip_address
    string
    IP address
    created_at
    datetime
    Creation timestamp

    Purchases

    POST /purchases

    • Example
    • Try It
    // Example Request Body
    {
      "order_id": "777B221-X",
      "payment_amount": 177.11,
      "new_customer": "yes",
      "coupon_code": "COUPON98765",
      "referral_code": "uxU",
      "email_address": "rory@example.za",
      "ip_address": "200.1.2.3",
      "referrer": "https://t.example.co/9Azx8",
      "customer_id": 89,
      "widget_id": 4,
      "products": [
        {
          "sku": "99P88Q77R",
          "quantity": 21,
          "price": 319.99
        }
      ]
    }
    
    // Example Response (201 CREATED)
    {
      "purchase": {
        "id": 3877,
        "order_id": "PQZ-4181",
        "coupon_code": "COUPON123456",
        "payment_amount": 15.97,
        "new_customer": "true",
        "ip_address": "200.1.2.3",
        "referrer": "https://t.example.co/9Azx8",
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "email_address": "adrian@example.fi",
        "customer": "https://developer-api.friendbuy.com/v2/customers/17",
        "products": [
          {
            "sku": "99P88Q77R",
            "quantity": 21,
            "price": 319.99
          }
        ],
        "created_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    Creates a purchase.

    Body Parameters

    order_id*
    Unique order id for the purchase. If this order id has been previously used, the request will fail with a 409 CONFLICT error and no new purchase will be created.
    payment_amount
    Amount of the order
    new_customer
    Whether or not the purchase is made by a new (first-time) customer. Used to check for reward eligibility, since Friendbuy allows merchants to state “must be a new customer” as one of the reward criteria. Allowed values are yes, no, unknown.
    coupon_code
    The friend’s coupon code, distributed via Friendbuy, applied at checkout. When present, we’ll attempt to automate a referral conversion with the purchase event.
    referral_code
    Unique string on Advocate’s referral link. When present, a conversion will be generated with the purchase event. Referral_code takes precedence over coupon_code.
    email_address
    Email associated with the order
    ip_address
    IP address
    referrer
    Referrer URL
    customer_id
    The id generated by and used internally by Friendbuy for your customer (not the same as the account id assigned to the customer by you). This can be obtained from your id by invoking GET /customers?account_id=
    widget_id
    Can be located on the Widget Installation Code tab within a widget management page, or via GET/widgets endpoint
    products[0].sku
    Product SKU
    products[0].quantity
    Number of units of the product that were purchased
    products[0].price
    Amount of the order, in currency units

    * Required field

    Response Model

    Purchase
    id
    integer
    Friendbuy-assigned id for the purchase
    order_id
    string
    Order Id of the purchase
    coupon_code
    string
    Present if a coupon code was used to make the purchase
    payment_amount
    number
    Total purchase amount reported
    new_customer
    boolean
    Whether or not the purchase was reported to have been made by a new (first-time) customer, one of true, false, or unknown
    ip_address
    string
    IP address
    referrer
    string
    Referrer URL
    widget
    string
    API link of the associated widget
    email_address
    string
    Email address of the purchaser if known
    customer
    string
    API link of the associated customer, if any
    products
    array
    List of products reported in the purchase (Expand)
    Product
    sku
    string
    Product SKU
    quantity
    number
    Number of units of the product that were purchased
    price
    number
    Amount of the order, in currency units
    created_at
    datetime
    Creation timestamp

    GET /purchases

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "next_page": "https://developer-api.friendbuy.com/v2/purchases?cursor=70",
      "results_count": 20,
      "results": [
        {
          "id": 3877,
          "order_id": "PQZ-4181",
          "coupon_code": "COUPON123456",
          "payment_amount": 15.97,
          "new_customer": "true",
          "ip_address": "200.1.2.3",
          "referrer": "https://t.example.co/9Azx8",
          "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
          "email_address": "adrian@example.fi",
          "customer": "https://developer-api.friendbuy.com/v2/customers/17",
          "products": [
            {
              "sku": "99P88Q77R",
              "quantity": 21,
              "price": 319.99
            }
          ],
          "created_at": "2017-01-13T19:18:38.239Z"
        }
      ]
    }
    
    // To see live output, click the Try It button
    

    Retrieves a list of purchases.

    Query Parameters

    cursor
    Value for pagination, obtained from the response of the previous page. Omitted when requesting the first page of results
    limit
    Maximum number of results to return for the page
    from
    First date of range (YYYY-MM-DD, inclusive)
    to
    Last date of range (YYYY-MM-DD, inclusive)
    widget_id
    Can be located on the Widget Installation Code tab within a widget management page, or via GET/widgets endpoint
    customer_id
    The id generated by and used internally by Friendbuy for your customer (not the same as the account id assigned to the customer by you). This can be obtained from your id by invoking GET /customers?account_id=
    order_id
    Your order id

    Response Model

    Purchase
    id
    integer
    Friendbuy-assigned id for the purchase
    order_id
    string
    Order Id of the purchase
    coupon_code
    string
    Present if a coupon code was used to make the purchase
    payment_amount
    number
    Total purchase amount reported
    new_customer
    boolean
    Whether or not the purchase was reported to have been made by a new (first-time) customer, one of true, false, or unknown
    ip_address
    string
    IP address
    referrer
    string
    Referrer URL
    widget
    string
    API link of the associated widget
    email_address
    string
    Email address of the purchaser if known
    customer
    string
    API link of the associated customer, if any
    products
    array
    List of products reported in the purchase (Expand)
    Product
    sku
    string
    Product SKU
    quantity
    number
    Number of units of the product that were purchased
    price
    number
    Amount of the order, in currency units
    created_at
    datetime
    Creation timestamp

    GET /purchases/{id}

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "purchase": {
        "id": 3877,
        "order_id": "PQZ-4181",
        "coupon_code": "COUPON123456",
        "payment_amount": 15.97,
        "new_customer": "true",
        "ip_address": "200.1.2.3",
        "referrer": "https://t.example.co/9Azx8",
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "email_address": "adrian@example.fi",
        "customer": "https://developer-api.friendbuy.com/v2/customers/17",
        "products": [
          {
            "sku": "99P88Q77R",
            "quantity": 21,
            "price": 319.99
          }
        ],
        "created_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    Retrieves the purchase with the given id.

    Path Parameters

    id*
    The internal id of the purchase

    *Required field

    Response Model

    Purchase
    id
    integer
    Friendbuy-assigned id for the purchase
    order_id
    string
    Order Id of the purchase
    coupon_code
    string
    Present if a coupon code was used to make the purchase
    payment_amount
    number
    Total purchase amount reported
    new_customer
    boolean
    Whether or not the purchase was reported to have been made by a new (first-time) customer, one of true, false, or unknown
    ip_address
    string
    IP address
    referrer
    string
    Referrer URL
    widget
    string
    API link of the associated widget
    email_address
    string
    Email address of the purchaser if known
    customer
    string
    API link of the associated customer, if any
    products
    array
    List of products reported in the purchase (Expand)
    Product
    sku
    string
    Product SKU
    quantity
    number
    Number of units of the product that were purchased
    price
    number
    Amount of the order, in currency units
    created_at
    datetime
    Creation timestamp

    Conversions

    A conversion occurs when (1) Friendbuy is notified of a purchase, and (2) we are able to associate the purchase to an advocate’s referral via the referral code or coupon code provided to their friend.

    You can notify Friendbuy of a purchase through a Track Order call via the Friendbuy JavaScript embedded on your site, or through the POST /purchases endpoint.

    POST /conversions

    • Example
    • Try It
    // Example Request Body
    {
      "purchase_id": 55,
      "referral_code": "uxU",
      "coupon_code": "COUPON98765"
    }
    
    // Example Response (201 CREATED)
    {
      "conversion": {
        "id": 121393,
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "customer": "https://developer-api.friendbuy.com/v2/customers/17",
        "purchase": "https://developer-api.friendbuy.com/v2/conversions/121393",
        "advocate_email_address": "alice@example.int",
        "channel": "facebook",
        "source": "https://developer-api.friendbuy.com/v2/shares/121393",
        "created_at": "2017-01-13T19:18:38.239Z",
        "last_modified_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    Creates a conversion.

    Body Parameters

    purchase_id*
    Id of the purchase that led to the conversion
    referral_code**
    Refcode (just the string, not the entire object) that referred the friend to make the purchase. Required unless coupon_code is present. If both referral_code and coupon_code are provided, referral_code will take precedence.
    coupon_code**
    Coupon code that brought the friend to the merchant to make the purchase. Required unless referral_code is present.

    * Required field
    ** At least one of these fields is required

    Response Model

    Conversion
    id
    integer
    Friendbuy internal id for this conversion
    widget
    string
    API link of the associated widget
    customer
    string
    API link of the associated customer, if any
    purchase
    string
    Purchase triggering the conversion if any
    advocate_email_address
    string
    Email address of the advocate, if known
    channel
    string
    One of email, facebook, twitter, messenger, personal_url, reminder_email, or unknown
    source
    string
    API link of the share, reminder email, or referral link (in the case of PURL conversions) from which the conversion was made
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    GET /conversions

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "next_page": "https://developer-api.friendbuy.com/v2/conversions?cursor=70",
      "results_count": 20,
      "results": [
        {
          "id": 121393,
          "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
          "customer": "https://developer-api.friendbuy.com/v2/customers/17",
          "purchase": "https://developer-api.friendbuy.com/v2/conversions/121393",
          "advocate_email_address": "alice@example.int",
          "channel": "facebook",
          "source": "https://developer-api.friendbuy.com/v2/shares/121393",
          "created_at": "2017-01-13T19:18:38.239Z",
          "last_modified_at": "2017-01-13T19:18:38.239Z"
        }
      ]
    }
    
    // To see live output, click the Try It button
    

    Retrieves a list of conversions.

    Query Parameters

    cursor
    Value for pagination, obtained from the response of the previous page. Omitted when requesting the first page of results
    limit
    Maximum number of results to return for the page
    from
    First date of range (YYYY-MM-DD, inclusive)
    to
    Last date of range (YYYY-MM-DD, inclusive)
    widget_id
    Can be located on the Widget Installation Code tab within a widget management page, or via GET/widgets endpoint
    customer_id
    The id generated by and used internally by Friendbuy for your customer (not the same as the account id assigned to the customer by you). This can be obtained from your id by invoking GET /customers?account_id=
    email_address
    The advocate's email address associated with the conversion

    Response Model

    Conversion
    id
    integer
    Friendbuy internal id for this conversion
    widget
    string
    API link of the associated widget
    customer
    string
    API link of the associated customer, if any
    purchase
    string
    Purchase triggering the conversion if any
    advocate_email_address
    string
    Email address of the advocate, if known
    channel
    string
    One of email, facebook, twitter, messenger, personal_url, reminder_email, or unknown
    source
    string
    API link of the share, reminder email, or referral link (in the case of PURL conversions) from which the conversion was made
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    GET /conversions/{id}

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "conversion": {
        "id": 121393,
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "customer": "https://developer-api.friendbuy.com/v2/customers/17",
        "purchase": "https://developer-api.friendbuy.com/v2/conversions/121393",
        "advocate_email_address": "alice@example.int",
        "channel": "facebook",
        "source": "https://developer-api.friendbuy.com/v2/shares/121393",
        "created_at": "2017-01-13T19:18:38.239Z",
        "last_modified_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    Retrieves the conversion with the given id.

    Path Parameters

    id*
    The internal id of the conversion

    *Required field

    Response Model

    Conversion
    id
    integer
    Friendbuy internal id for this conversion
    widget
    string
    API link of the associated widget
    customer
    string
    API link of the associated customer, if any
    purchase
    string
    Purchase triggering the conversion if any
    advocate_email_address
    string
    Email address of the advocate, if known
    channel
    string
    One of email, facebook, twitter, messenger, personal_url, reminder_email, or unknown
    source
    string
    API link of the share, reminder email, or referral link (in the case of PURL conversions) from which the conversion was made
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    Rewards

    A reward is an optional referral incentive triggered by a conversion. For each conversion occurence, Friendbuy will check whether the widget variant associated with the referral is configured with a reward. If a reward configuration was specified, Friendbuy will evaluate the conversion against the reward criteria and enabled fraud checks to determine if a reward should be approved. If the conversion passes all checks, the reward is approved. If not, the reward is marked rejected.

    GET /rewards

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "next_page": "https://developer-api.friendbuy.com/v2/rewards?cursor=70",
      "results_count": 20,
      "results": [
        {
          "id": 3181,
          "type": "fixed_cash",
          "status": "valid",
          "amount": 10,
          "rejected_reasons": "",
          "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
          "customer": "https://developer-api.friendbuy.com/v2/customers/17",
          "conversion": "https://developer-api.friendbuy.com/v2/conversions/121393",
          "evaluate_at": "2017-01-13T19:20:38.211Z",
          "created_at": "2017-01-13T19:18:38.239Z",
          "last_modified_at": "2017-01-13T19:18:38.239Z"
        }
      ]
    }
    
    // To see live output, click the Try It button
    

    Retrieves a list of rewards.

    Query Parameters

    cursor
    Value for pagination, obtained from the response of the previous page. Omitted when requesting the first page of results
    limit
    Maximum number of results to return for the page
    from
    First date of range (YYYY-MM-DD, inclusive)
    to
    Last date of range (YYYY-MM-DD, inclusive)
    widget_id
    Can be located on the Widget Installation Code tab within a widget management page, or via GET/widgets endpoint
    customer_id
    The id generated by and used internally by Friendbuy for your customer (not the same as the account id assigned to the customer by you). This can be obtained from your id by invoking GET /customers?account_id=
    conversion_id
    The conversion to which the rewards belong

    Response Model

    Reward
    id
    integer
    Friendbuy internal id for the reward
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    status
    string
    One of pending, valid, or invalid
    amount
    number
    Amount of the reward in units of the reward type
    rejected_reasons
    string
    An object describing the self referral and reward criteria that triggered the reward to be rejected instead of approved
    widget
    string
    API link of the associated widget
    customer
    string
    API link of the associated customer, if any
    conversion
    string
    Conversion of the reward
    evaluate_at
    datetime
    Timestamp at which the reward validity was scheduled to be evaluated
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    GET /rewards/{id}

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "reward": {
        "id": 3181,
        "type": "fixed_cash",
        "status": "valid",
        "amount": 10,
        "rejected_reasons": "",
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "customer": "https://developer-api.friendbuy.com/v2/customers/17",
        "conversion": "https://developer-api.friendbuy.com/v2/conversions/121393",
        "evaluate_at": "2017-01-13T19:20:38.211Z",
        "created_at": "2017-01-13T19:18:38.239Z",
        "last_modified_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    Retrieves the reward with the given id.

    Path Parameters

    id*
    The internal id of the reward

    *Required field

    Response Model

    Reward
    id
    integer
    Friendbuy internal id for the reward
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    status
    string
    One of pending, valid, or invalid
    amount
    number
    Amount of the reward in units of the reward type
    rejected_reasons
    string
    An object describing the self referral and reward criteria that triggered the reward to be rejected instead of approved
    widget
    string
    API link of the associated widget
    customer
    string
    API link of the associated customer, if any
    conversion
    string
    Conversion of the reward
    evaluate_at
    datetime
    Timestamp at which the reward validity was scheduled to be evaluated
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    Coupons

    GET /coupon_banks

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "next_page": "https://developer-api.friendbuy.com/v2/coupon_banks?cursor=70",
      "results_count": 20,
      "results": [
        {
          "id": 1,
          "name": "Fall promotion",
          "description": "Coupons for fall promotion",
          "alert_threshold": 400,
          "active": true,
          "created_at": "2017-01-13T19:18:38.239Z"
        }
      ]
    }
    
    // To see live output, click the Try It button
    

    Retrieves a list of coupon banks.

    Query Parameters

    cursor
    Value for pagination, obtained from the response of the previous page. Omitted when requesting the first page of results
    limit
    Maximum number of results to return for the page

    Response Model

    CouponBank
    id
    integer
    Coupon bank ID
    name
    string
    Name of the coupon bank
    description
    string
    Description of the coupon bank
    alert_threshold
    integer
    An email will be sent to you when the coupon bank drops below this amount
    active
    boolean
    Whether the coupon bank is active
    created_at
    datetime
    Creation timestamp

    GET /coupon_banks/{id}

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "coupon_bank": {
        "id": 1,
        "name": "Fall promotion",
        "description": "Coupons for fall promotion",
        "alert_threshold": 400,
        "active": true,
        "created_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    Retrieves the coupon bank with the given id.

    Path Parameters

    id*
    The internal id of the coupon bank

    *Required field

    Response Model

    CouponBank
    id
    integer
    Coupon bank ID
    name
    string
    Name of the coupon bank
    description
    string
    Description of the coupon bank
    alert_threshold
    integer
    An email will be sent to you when the coupon bank drops below this amount
    active
    boolean
    Whether the coupon bank is active
    created_at
    datetime
    Creation timestamp

    GET /coupons

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "next_page": "https://developer-api.friendbuy.com/v2/coupons?cursor=70",
      "results_count": 20,
      "results": [
        {
          "id": 1,
          "code": "COUPON123456",
          "coupon_bank": "#{API_BASE_URI}/coupon_banks/121393",
          "email_address": "delia@example.net",
          "created_at": "2017-01-13T19:18:38.239Z",
          "last_modified_at": "2017-01-13T19:18:38.239Z"
        }
      ]
    }
    
    // To see live output, click the Try It button
    

    Retrieves a list of coupons.

    Query Parameters

    cursor
    Value for pagination, obtained from the response of the previous page. Omitted when requesting the first page of results
    limit
    Maximum number of results to return for the page
    from
    First date of range (YYYY-MM-DD, inclusive)
    to
    Last date of range (YYYY-MM-DD, inclusive)
    customer_id
    The id generated by and used internally by Friendbuy for your customer (not the same as the account id assigned to the customer by you). This can be obtained from your id by invoking GET /customers?account_id=
    Specifying customer_id will retrieve the coupons for the rewards this customer has earned

    email_address
    The email address associated with the coupon

    Response Model

    Coupon
    id
    integer
    Coupon ID
    code
    string
    Coupon code
    coupon_bank
    string
    API link of the coupon bank
    email_address
    string
    Email address associated with this coupon, if any
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    Clicks

    GET /clicks

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "next_page": "https://developer-api.friendbuy.com/v2/clicks?cursor=70",
      "results_count": 20,
      "results": [
        {
          "id": 599393,
          "ip_address": "8.8.8.8",
          "referrer": "https://t.example.co/9Azx8",
          "type": "shareclick",
          "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
          "customer": "https://developer-api.friendbuy.com/v2/customers/17",
          "email": "delia@example.net",
          "source": "https://developer-api.friendbuy.com/v2/shares/93813",
          "created_at": "2017-01-13T19:18:38.239Z"
        }
      ]
    }
    
    // To see live output, click the Try It button
    

    Retrieves a list of clicks.

    Query Parameters

    cursor
    Value for pagination, obtained from the response of the previous page. Omitted when requesting the first page of results
    limit
    Maximum number of results to return for the page
    from
    First date of range (YYYY-MM-DD, inclusive)
    to
    Last date of range (YYYY-MM-DD, inclusive)
    widget_id
    Can be located on the Widget Installation Code tab within a widget management page, or via GET/widgets endpoint
    customer_id
    The id generated by and used internally by Friendbuy for your customer (not the same as the account id assigned to the customer by you). This can be obtained from your id by invoking GET /customers?account_id=
    email_address
    The email address associated with the click

    Response Model

    Click
    id
    integer
    Friendbuy internal id for this click
    ip_address
    string
    IP address associated with the click
    referrer
    string
    Referrer URL
    type
    string
    One of shareclick, personalurlclick, or reminderemailclick
    widget
    string
    API link of the associated widget
    customer
    string
    API link of the associated customer, if any
    email
    string
    Email address associated with the click
    source
    string
    API link for the share, referral link, or reminder email associated with the click
    created_at
    datetime
    Creation timestamp

    Newsletter Opt Ins

    Selected Friendbuy widgets enable users to opt in to receiving future newsletter communications from your company.

    GET /newsletter_opt_ins

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "next_page": "https://developer-api.friendbuy.com/v2/newsletter_opt_ins?cursor=70",
      "results_count": 20,
      "results": [
        {
          "email": "delia@example.net",
          "source": "https://developer-api.friendbuy.com/v2/shares/93813",
          "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
          "created_at": "2017-01-13T19:18:38.239Z"
        }
      ]
    }
    
    // To see live output, click the Try It button
    

    Retrieves the list of email addresses that have opted in to receiving newsletter emails

    Query Parameters

    cursor
    Value for pagination, obtained from the response of the previous page. Omitted when requesting the first page of results
    limit
    Maximum number of results to return for the page
    from
    First date of range (YYYY-MM-DD, inclusive)
    to
    Last date of range (YYYY-MM-DD, inclusive)
    widget_id
    Can be located on the Widget Installation Code tab within a widget management page, or via GET/widgets endpoint
    source
    One of share or email_capture. Required.

    Response Model

    NewsletterOptIn
    email
    string
    Email address that has opted in
    source
    string
    API link of the share or the email capture in which the email opted in
    widget
    string
    API link of the associated widget
    created_at
    datetime
    Creation timestamp

    Email Opt Outs

    Friendbuy maintains a list of email addresses for users who have opted out of receiving referral-related email communications from Friendbuy on behalf of your company. This list is always cross-referenced prior to sending emails from our system. For information about integrating Friendbuy with your own API endpoint, please refrer to the Email Recipient Authorization.

    POST /jobs/email_opt_outs

    • Example
    • Try It
    // Example Request Body
    {
      "emails": [
        "pele@example.br, messi@example.ar, neuer@example.de"
      ]
    }
    
    // Example Response (202 ACCEPTED)
    {
      "job": {
        "id": 15,
        "filename": "/tmp/907bf7ce2211aa",
        "status": "Success",
        "total_items_count": 89,
        "updated_items_count": 55,
        "failure_reason": "",
        "created_at": "2017-01-13T19:18:38.239Z",
        "last_modified_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    In addition to allowing users to opt out through an unsubscribe link in email shares, you can upload a list of email addresses that is maintained by your company.

    Body Parameters

    emails*
    Array of email addresses to opt out (enter as a comma-separated list to try out)

    * Required field

    Response Model

    Job
    id
    integer
    Job id
    filename
    string
    Filename
    status
    string
    One of Success, Failed, or In Progress
    total_items_count
    integer
    Total items requested to be processed by this job
    updated_items_count
    integer
    Number of items processed so far by this job
    failure_reason
    string
    Failure reason
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    GET /jobs/email_opt_outs/{id}

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "job": {
        "id": 15,
        "filename": "/tmp/907bf7ce2211aa",
        "status": "Success",
        "total_items_count": 89,
        "updated_items_count": 55,
        "failure_reason": "",
        "created_at": "2017-01-13T19:18:38.239Z",
        "last_modified_at": "2017-01-13T19:18:38.239Z"
      }
    }
    
    // To see live output, click the Try It button
    

    Retrieves the status of an email opt out job.

    Path Parameters

    id*
    The job id, returned in the response to the job creation input

    *Required field

    Response Model

    Job
    id
    integer
    Job id
    filename
    string
    Filename
    status
    string
    One of Success, Failed, or In Progress
    total_items_count
    integer
    Total items requested to be processed by this job
    updated_items_count
    integer
    Number of items processed so far by this job
    failure_reason
    string
    Failure reason
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    GET /email_opt_outs

    • Example
    • Try It
    // Example Response (200 OK)
    {
      "next_page": "https://developer-api.friendbuy.com/v2/email_opt_outs?cursor=70",
      "results_count": 20,
      "results": [
        {
          "id": 19,
          "email": "delia@example.net",
          "ip_address": "8.8.8.8",
          "source": "upload",
          "created_at": "2017-01-13T19:18:38.239Z"
        }
      ]
    }
    
    // To see live output, click the Try It button
    

    Retrieves a list of opted-out email addresses.

    Query Parameters

    cursor
    Value for pagination, obtained from the response of the previous page. Omitted when requesting the first page of results
    limit
    Maximum number of results to return for the page
    from
    First date of range (YYYY-MM-DD, inclusive)
    to
    Last date of range (YYYY-MM-DD, inclusive)

    Response Model

    EmailOptOut
    id
    integer
    Id of the opt out record
    email
    string
    Email address on the opt out list
    ip_address
    string
    IP address associated with the opt out
    source
    string
    Source of the opt_out_list, either share if the opt out was made from a share widget, or upload if part of an uploaded opt out list
    created_at
    datetime
    Creation timestamp

    User Data

    The user data endpoints support CCPA and GDPR requests for reports of user data stored, and deletion of user data.

    POST /user_data/request_report

    • Example
    • Try It
    // Example Request Body
    {
      "email_addresses": [
        "pele@example.br",
        "messi@example.ar",
        "neuer@example.de"
      ],
      "notification_email": "tgo@example.net"
    }
    
    // Example Response (200 OK)
    {
      "message": "Request received",
      "task_id": "abc123"
    }
    
    // To see live output, click the Try It button
    

    Request a report of the data stored for a list of user email addresses. You will receive an email with a link to the report at the email provided.

    Body Parameters

    email_addresses*
    Array of email addresses to opt out (enter as a comma-separated list to try out)
    notification_email*
    An email to receive notification when task is completed

    * Required field

    Response Model

    UserDataResponse
    message
    string
    Message indicating success or failure for the request
    task_id
    string
    An id for the task executing the operation

    POST /user_data/delete

    • Example
    • Try It
    // Example Request Body
    {
      "email_addresses": [
        "pele@example.br",
        "messi@example.ar",
        "neuer@example.de"
      ],
      "notification_email": "tgo@example.net"
    }
    
    // Example Response (200 OK)
    {
      "message": "Request received",
      "task_id": "abc123"
    }
    
    // To see live output, click the Try It button
    

    Delete the data stored for a list of user email addresses.

    Body Parameters

    email_addresses*
    Array of email addresses to opt out (enter as a comma-separated list to try out)
    notification_email*
    An email to receive notification when task is completed

    * Required field

    Response Model

    UserDataResponse
    message
    string
    Message indicating success or failure for the request
    task_id
    string
    An id for the task executing the operation

    Webhooks

    Friendbuy’s webhooks provide real-time notifications to your system based on data created by a referral program. Use webhooks to:

    When invoking webhooks and integrating with APIs on your servers, Friendbuy will use the secret key to sign requests.

    Example Python Signature Computation

    from base64 import b64encode
    from hashlib import sha1
    import hmac
    def create_signature(api_secret, data):
        mac = hmac.new(api_secret.encode('utf-8'), data.encode('utf-8'), sha1)
        computed = b64encode(mac.digest())
        return computed.strip()
    

    You can verify the authenticity of a webhook request or client API integration from Friendbuy by analyzing its cryptographic signature. When Friendbuy sends a request to your endpoints, a signature is placed in the X-FRIENDBUY-SIGNATURE header (X-FRIENDBUY-SIGNATURE-V2 for custom reward validation), and is computed by Base64-encoding the HMAC-SHA1 hash of the request body with your Friendbuy secret key. To verify the signature:

    1. Calculate an HMAC-SHA1 composition of the JSON request body: HMAC(api_secret, json_body)
    2. Base64 encode the resulting value.
    3. If the Base64 encoded hash matches the signature header, the request is valid.

    To provide better flexibility for customers that have specific header signature requirements, Friendbuy can now include custom headers as an alternative to our standard signature. For example, you may wish Friendbuy to supply the access token ac33-pXAP under the header Api-Access-Token. Friendbuy will then append the header in each webhook or integration request:

    Api-Access-Token=ac33-pXAP

    Custom headers can also be utilized for purposes other than security. For instance, if your webhook or integration url handles posts from more than one service, a vendor identifier could be used to indicate Friendbuy is the requesting vendor, for example:

    Webhook-Consumer-Id=friendbuy

    This feature is supported for all webhooks and client integration callbacks. For more details about utilizing custom headers, please contact your Friendbuy Customer Success Manager.

    Each available webhook is documented below. For each webhook, a complete technical specification of the data model is provided in the center pane. The right-hand pane contains an example of such a JSON request.

    Share Webhook

    Example Post Body for Webhook

    {
      "id": 196418,
      "referral_code": "uxC",
      "message": {
        "id": "100001965159666_428859647189537",
        "content": "This is my favorite tennis racket ever",
        "network": "facebook"
      },
      "campaign": {
        "id": 233,
        "name": "Fall Shoe Sale",
        "published": true,
        "referral_incentive": {
          "type": "fixed_cash",
          "value": 25
        },
        "created_at": "2015-08-09T03:20:11.098230-07:00"
      },
      "ip_address": "8.8.8.8",
      "newsletter_opt_in": true,
      "send_reminder": true,
      "created_at": "2017-01-13T19:18:38.239Z",
      "detail_uri": "https://developer-api.friendbuy.com/v2/shares/196418",
      "email_recipients": [
        "pele@example.br",
        "messi@example.ar"
      ],
      "sharer": {
        "name": "Taylor Gomez",
        "email": "tgo@example.net",
        "customer": {
          "account_id": "JAYZ",
          "id": "JAYZ",
          "email_address": "jzheng@example.mil",
          "first_name": "Jaylene",
          "last_name": "Zheng",
          "stripe_customer_id": "cus_Agg4bCEhno7A1E",
          "chargebee_customer_id": "4gkYnd21ouvW",
          "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
        },
        "facebook_friends_count": 987,
        "twitter_followers_count": 121393,
        "birthdate": "1989-11-09"
      }
    }
    

    A share occurs when an advocate refers a friend directly through a Friendbuy widget. The share will be associated to a specific channel, such as email, Facebook, or Twitter.

    After a successful share, Friendbuy will send a POST request to your system with data about the share. Share webhooks are triggered only in response to direct shares, and not to dissemination of a Personal URL (PURL).

    Request Model

    ShareExcerpt
    id
    integer
    Friendbuy internal id for this share
    referral_code
    string
    Short alphanumeric code
    message
    object
    Message sent along with share (Expand)
    ShareMessage
    id
    string
    Message id assigned by facebook or twitter
    content
    string
    Text entered by the advocate
    network
    string
    Distribution channel for this share
    campaign
    object
    Campaign that is being shared (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    ip_address
    string
    IP address of the share
    newsletter_opt_in
    boolean
    Whether a newsletter opt in should take place with the share
    send_reminder
    boolean
    Whether a reminder should be sent for the share
    created_at
    datetime
    Share creation timestamp
    detail_uri
    string
    URI endpoint at which to get full details of the share
    email_recipients
    array
    JSON-formatted array of recipients for the share, present only if (1) the share is an email share and (2) the merchant is permitted to access this information (*Contact Friendbuy to inquire about the ability to access the recipient list*)
    sharer
    object
    Information for the entity making the share (Expand)
    SharerExcerpt
    name
    string
    Name of sharer, if known
    email
    string
    Email address to receive the reward, if eventually eligible
    customer
    object
    Customer information, if available at the time of share (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    facebook_friends_count
    integer
    Number of Facebook friends, if known
    twitter_followers_count
    integer
    Number of Twitter followers, if known
    birthdate
    date
    Birthdate, if known

    Email Capture Webhook

    Example Post Body for Webhook

    {
      "id": 362752,
      "email_address": "jwu@gmail.com",
      "coupon_code": "BOGO-8910",
      "custom_properties": {
        "birthdate": "1969-07-28",
        "tel": "343-555-8680",
        "zipcode": "45678"
      },
      "campaign": {
        "id": 233,
        "name": "Fall Shoe Sale",
        "published": true,
        "referral_incentive": {
          "type": "fixed_cash",
          "value": 25
        },
        "created_at": "2015-08-09T03:20:11.098230-07:00"
      },
      "created_at": "2018-02-21T19:12:38.239Z",
      "referrer": {
        "customer": {
          "account_id": "JAYZ",
          "id": "JAYZ",
          "email_address": "jzheng@example.mil",
          "first_name": "Jaylene",
          "last_name": "Zheng",
          "stripe_customer_id": "cus_Agg4bCEhno7A1E",
          "chargebee_customer_id": "4gkYnd21ouvW",
          "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
        },
        "email": "alex@example.ca",
        "name": "Taylor Gomez",
        "facebook_friends_count": 987,
        "twitter_followers_count": 121393,
        "birthdate": "1989-11-09"
      },
      "referral_code": "uxC",
      "newsletter_opt_in": true,
      "ip_address": "8.8.8.8",
      "purchase_history_validation_passed": false
    }
    

    An email capture event occurs when a referred friend or site visitor submits their email address through an email capture widget.

    After a successful email capture, Friendbuy will send a POST request to your system with data about the email capture, the visitor, and offer (if applicable). If the visitor is a referred friend, details about the referring advocate will also be included.

    Request Model

    EmailCaptureExcerpt
    id
    integer
    Friendbuy internal id for this email capture
    email_address
    string
    The email address that was captured
    coupon_code
    string
    The coupon code that was provided after email capture, if given
    custom_properties
    object
    Additional data collected by the email capture widget
    campaign
    object
    Campaign for this email capture (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    created_at
    datetime
    Email capture creation timestamp
    referrer
    object
    Information about the advocate who referred the email capture (Expand)
    Referrer
    customer
    object
    Present only if referral is a customer personal url or a share with a known customer (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    email
    string
    Present only if referral is an email personal url or a share with a known referring email
    name
    string
    Name of referrer, if conversion was from a share
    facebook_friends_count
    integer
    Number of Facebook friends of sharer, if known
    twitter_followers_count
    integer
    Number of Twitter followers of sharer, if known
    birthdate
    date
    Birthdate of sharer, if known
    referral_code
    string
    Short alphanumeric code (e.g., uxC)
    newsletter_opt_in
    boolean
    Whether a newsletter opt in should take place with the email capture
    ip_address
    string
    IP address associated with the email capture
    purchase_history_validation_passed
    boolean
    Indicates if Friendbuy has already recorded a purchase associated with the email address provided by the visitor. This property is only included in the payload for email capture widgets that have this validation check enabled.

    Conversion Webhook

    Example Post Body for Webhook

    {
      "id": 121393,
      "status": "paid",
      "type": "share",
      "campaign": {
        "id": 233,
        "name": "Fall Shoe Sale",
        "published": true,
        "referral_incentive": {
          "type": "fixed_cash",
          "value": 25
        },
        "created_at": "2015-08-09T03:20:11.098230-07:00"
      },
      "purchase": {
        "order_id": "PQZ-4181",
        "coupon_code": "COUPON123456",
        "date": "2017-04-01T11:07:40.904Z",
        "total": 15.97,
        "new_customer": "true",
        "email": "adrian@example.fi",
        "ip_address": "200.1.2.3",
        "products": [
          {
            "sku": "99P88Q77R",
            "quantity": 21,
            "price": 319.99
          }
        ],
        "customer": {
          "account_id": "JAYZ",
          "id": "JAYZ",
          "email_address": "jzheng@example.mil",
          "first_name": "Jaylene",
          "last_name": "Zheng",
          "stripe_customer_id": "cus_Agg4bCEhno7A1E",
          "chargebee_customer_id": "4gkYnd21ouvW",
          "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
        }
      },
      "detail_uri": "https://developer-api.friendbuy.com/v2/conversions/121393",
      "created_at": "2016-03-01T19:12:38.239Z",
      "possible_self_referral": true,
      "fraud": {
        "same_shopper": false,
        "same_customer": false,
        "same_email": false,
        "same_ip_address": false,
        "same_ip_and_user_agent": false,
        "fuzzy_email": false,
        "high_sensitivity_fuzzy_email": false
      },
      "reward": "null",
      "personal_url": {
        "referral_code": "uxC",
        "trackable_link": "http://fbuy.me/uxC",
        "destination_url": "http://mycompany.example.com/rewards/908",
        "referral_code_blacklisted": true
      },
      "share": {
        "id": 196418,
        "referral_code": "uxC",
        "message": {
          "id": "100001965159666_428859647189537",
          "content": "This is my favorite tennis racket ever",
          "network": "facebook"
        },
        "campaign": {
          "id": 233,
          "name": "Fall Shoe Sale",
          "published": true,
          "referral_incentive": {
            "type": "fixed_cash",
            "value": 25
          },
          "created_at": "2015-08-09T03:20:11.098230-07:00"
        },
        "ip_address": "8.8.8.8",
        "newsletter_opt_in": true,
        "send_reminder": true,
        "created_at": "2017-01-13T19:18:38.239Z",
        "detail_uri": "https://developer-api.friendbuy.com/v2/shares/196418",
        "email_recipients": [
          "pele@example.br",
          "messi@example.ar"
        ],
        "sharer": {
          "name": "Taylor Gomez",
          "email": "tgo@example.net",
          "customer": {
            "account_id": "JAYZ",
            "id": "JAYZ",
            "email_address": "jzheng@example.mil",
            "first_name": "Jaylene",
            "last_name": "Zheng",
            "stripe_customer_id": "cus_Agg4bCEhno7A1E",
            "chargebee_customer_id": "4gkYnd21ouvW",
            "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
          },
          "facebook_friends_count": 987,
          "twitter_followers_count": 121393,
          "birthdate": "1989-11-09"
        }
      },
      "reminder_email": {
        "id": 377,
        "customer": "https://developer-api.friendbuy.com/v2/customers/17",
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "share": "https://developer-api.friendbuy.com/v2/shares/93813",
        "referral_link": "https://developer-api.friendbuy.com/v2/referral_links/uXc",
        "advocate_email_address": "jzheng@example.mil",
        "email_recipients_count": 100,
        "created_at": "2017-01-13T19:18:38.239Z",
        "last_modified_at": "2017-01-13T19:18:38.239Z"
      },
      "referrer": {
        "customer": {
          "account_id": "JAYZ",
          "id": "JAYZ",
          "email_address": "jzheng@example.mil",
          "first_name": "Jaylene",
          "last_name": "Zheng",
          "stripe_customer_id": "cus_Agg4bCEhno7A1E",
          "chargebee_customer_id": "4gkYnd21ouvW",
          "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
        },
        "email": "alex@example.ca",
        "name": "Taylor Gomez",
        "facebook_friends_count": 987,
        "twitter_followers_count": 121393,
        "birthdate": "1989-11-09"
      },
      "rewards": [
        {
          "id": 3181,
          "status": "invalid",
          "type": "fixed_cash",
          "amount": 10,
          "rejected_reasons": {
            "same_customer": "same customer ID detected",
            "same_email": "same email detected",
            "fuzzy_email": "similar email detected"
          },
          "created_at": "2017-01-13T19:18:38.239Z",
          "evaluate_at": "2017-01-13T19:20:38.211Z",
          "conversion": {
            "id": 121393,
            "status": "paid",
            "type": "share",
            "campaign": {
              "id": 233,
              "name": "Fall Shoe Sale",
              "published": true,
              "referral_incentive": {
                "type": "fixed_cash",
                "value": 25
              },
              "created_at": "2015-08-09T03:20:11.098230-07:00"
            },
            "purchase": {
              "order_id": "PQZ-4181",
              "coupon_code": "COUPON123456",
              "date": "2017-04-01T11:07:40.904Z",
              "total": 15.97,
              "new_customer": "true",
              "email": "adrian@example.fi",
              "ip_address": "200.1.2.3",
              "products": [
                {
                  "sku": "99P88Q77R",
                  "quantity": 21,
                  "price": 319.99
                }
              ],
              "customer": {
                "account_id": "JAYZ",
                "id": "JAYZ",
                "email_address": "jzheng@example.mil",
                "first_name": "Jaylene",
                "last_name": "Zheng",
                "stripe_customer_id": "cus_Agg4bCEhno7A1E",
                "chargebee_customer_id": "4gkYnd21ouvW",
                "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
              }
            },
            "detail_uri": "https://developer-api.friendbuy.com/v2/conversions/121393",
            "created_at": "2016-03-01T19:12:38.239Z",
            "possible_self_referral": true,
            "fraud": {
              "same_shopper": false,
              "same_customer": false,
              "same_email": false,
              "same_ip_address": false,
              "same_ip_and_user_agent": false,
              "fuzzy_email": false,
              "high_sensitivity_fuzzy_email": false
            },
            "reward": "null",
            "personal_url": {
              "referral_code": "uxC",
              "trackable_link": "http://fbuy.me/uxC",
              "destination_url": "http://mycompany.example.com/rewards/908",
              "referral_code_blacklisted": true
            },
            "share": {
              "id": 196418,
              "referral_code": "uxC",
              "message": {
                "id": "100001965159666_428859647189537",
                "content": "This is my favorite tennis racket ever",
                "network": "facebook"
              },
              "campaign": {
                "id": 233,
                "name": "Fall Shoe Sale",
                "published": true,
                "referral_incentive": {
                  "type": "fixed_cash",
                  "value": 25
                },
                "created_at": "2015-08-09T03:20:11.098230-07:00"
              },
              "ip_address": "8.8.8.8",
              "newsletter_opt_in": true,
              "send_reminder": true,
              "created_at": "2017-01-13T19:18:38.239Z",
              "detail_uri": "https://developer-api.friendbuy.com/v2/shares/196418",
              "email_recipients": [
                "pele@example.br",
                "messi@example.ar"
              ],
              "sharer": {
                "name": "Taylor Gomez",
                "email": "tgo@example.net",
                "customer": {
                  "account_id": "JAYZ",
                  "id": "JAYZ",
                  "email_address": "jzheng@example.mil",
                  "first_name": "Jaylene",
                  "last_name": "Zheng",
                  "stripe_customer_id": "cus_Agg4bCEhno7A1E",
                  "chargebee_customer_id": "4gkYnd21ouvW",
                  "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
                },
                "facebook_friends_count": 987,
                "twitter_followers_count": 121393,
                "birthdate": "1989-11-09"
              }
            },
            "reminder_email": {
              "id": 377,
              "customer": "https://developer-api.friendbuy.com/v2/customers/17",
              "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
              "share": "https://developer-api.friendbuy.com/v2/shares/93813",
              "referral_link": "https://developer-api.friendbuy.com/v2/referral_links/uXc",
              "advocate_email_address": "jzheng@example.mil",
              "email_recipients_count": 100,
              "created_at": "2017-01-13T19:18:38.239Z",
              "last_modified_at": "2017-01-13T19:18:38.239Z"
            },
            "referrer": {
              "customer": {
                "account_id": "JAYZ",
                "id": "JAYZ",
                "email_address": "jzheng@example.mil",
                "first_name": "Jaylene",
                "last_name": "Zheng",
                "stripe_customer_id": "cus_Agg4bCEhno7A1E",
                "chargebee_customer_id": "4gkYnd21ouvW",
                "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
              },
              "email": "alex@example.ca",
              "name": "Taylor Gomez",
              "facebook_friends_count": 987,
              "twitter_followers_count": 121393,
              "birthdate": "1989-11-09"
            }
          }
        }
      ]
    }
    

    A conversion occurs when (1) Friendbuy is notified of a purchase and (2) we are able to associate to that purchase to an advocate’s referral via the referral code or coupon code provided to their friend.

    You can notify Friendbuy of a purchase through a Track Order call via the Friendbuy JavaScript embedded on your site, or through the POST /purchases endpoint.

    After a successful conversion, Friendbuy will send a POST request to your system containing data about the conversion.

    Request Model

    ConversionExcerpt
    id
    integer
    Friendbuy internal id for this conversion
    status
    string
    One of unmarked, paid, or rejected
    type
    string
    One of share, customer_personal_url, email_personal_url, or reminder_email
    campaign
    object
    Campaign for this reward (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    purchase
    object
    Purchase triggering the conversion if any (Expand)
    PurchaseExcerpt
    order_id
    string
    Order Id of the purchase
    coupon_code
    string
    Present if a coupon code was used to make the purchase
    date
    string
    Timestamp of purchase (missing time zone)
    total
    number
    Total purchase amount reported
    new_customer
    boolean
    Whether or not the purchase was reported to have been made by a new (first-time) customer, one of true, false, or unknown
    email
    string
    Email address of the purchaser if known
    ip_address
    string
    IP address
    products
    array
    List of products reported in the purchase (Expand)
    Product
    sku
    string
    Product SKU
    quantity
    number
    Number of units of the product that were purchased
    price
    number
    Amount of the order, in currency units
    customer
    object
    Customer making the purchase, if known (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    detail_uri
    string
    Friendbuy REST API resource for the conversion
    created_at
    datetime
    Conversion creation timestamp
    possible_self_referral
    boolean
    Whether the conversion may have come from an advocate using their own referral. This is done by comparing the data collected at time of a purchase to the data collected at time the share, PURL, or reminder email is generated. Note: this calculation is dependent on which fraud check settings have been enabled in the Friendbuy platform (specifically, the browser, customer id, email address, and IP address checks)
    fraud
    object
    Brief report on the presence or absence of various fraud conditions (Expand)
    FraudChecks
    same_shopper
    boolean
    Whether the same browser was used in both referral and purchase
    same_customer
    boolean
    Whether the merchant-assigned customer ids of the advocate and purchaser match
    same_email
    boolean
    Whether the email addresses of the advocate and purchaser match exactly
    same_ip_address
    boolean
    Whether the IP addresses of the advocate and purchaser match exactly
    same_ip_and_user_agent
    boolean
    Whether both the IP addresses and the user agent strings of the advocate and purchaser match exactly
    fuzzy_email
    boolean
    Whether the email addresses of the advocate and purchaser are _very_ similar
    high_sensitivity_fuzzy_email
    boolean
    Whether the email addresses of the advocate and purchaser are _loosely_ similar
    rewardDeprecated, always null
    personal_url
    object
    Present only if conversion was triggered from a PURL (Expand)
    ReferralCodeExcerpt
    referral_code
    string
    Short alphanumeric code (e.g., uxC)
    trackable_link
    string
    URI formed from the shortened domain together with the short code
    destination_url
    string
    URI in the merchant’s site that the trackable link redirects to
    referral_code_blacklisted
    boolean
    States if referral code has been invalidated from redirecting users to offer, managed within Referral Code Blacklist in the application.
    share
    object
    Present only if conversion was triggered from a share (Expand)
    ShareExcerpt
    id
    integer
    Friendbuy internal id for this share
    referral_code
    string
    Short alphanumeric code
    message
    object
    Message sent along with share (Expand)
    ShareMessage
    id
    string
    Message id assigned by facebook or twitter
    content
    string
    Text entered by the advocate
    network
    string
    Distribution channel for this share
    campaign
    object
    Campaign that is being shared (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    ip_address
    string
    IP address of the share
    newsletter_opt_in
    boolean
    Whether a newsletter opt in should take place with the share
    send_reminder
    boolean
    Whether a reminder should be sent for the share
    created_at
    datetime
    Share creation timestamp
    detail_uri
    string
    URI endpoint at which to get full details of the share
    email_recipients
    array
    JSON-formatted array of recipients for the share, present only if (1) the share is an email share and (2) the merchant is permitted to access this information (*Contact Friendbuy to inquire about the ability to access the recipient list*)
    sharer
    object
    Information for the entity making the share (Expand)
    SharerExcerpt
    name
    string
    Name of sharer, if known
    email
    string
    Email address to receive the reward, if eventually eligible
    customer
    object
    Customer information, if available at the time of share (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    facebook_friends_count
    integer
    Number of Facebook friends, if known
    twitter_followers_count
    integer
    Number of Twitter followers, if known
    birthdate
    date
    Birthdate, if known
    reminder_email
    object
    Present only if conversion was triggered from a reminder email (Expand)
    ReminderEmail
    id
    integer
    Friendbuy-assigned id for the reminder email
    customer
    string
    API link of the associated customer, if any
    widget
    string
    API link of the associated widget
    share
    string
    API link of the associated share.
    referral_link
    string
    API link of the referral link
    advocate_email_address
    string
    Email address of the advocate
    email_recipients_count
    integer
    Number of email recipients of the original share
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification
    referrer
    object
    Information about the advocate creating the conversion (Expand)
    Referrer
    customer
    object
    Present only if referral is a customer personal url or a share with a known customer (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    email
    string
    Present only if referral is an email personal url or a share with a known referring email
    name
    string
    Name of referrer, if conversion was from a share
    facebook_friends_count
    integer
    Number of Facebook friends of sharer, if known
    twitter_followers_count
    integer
    Number of Twitter followers of sharer, if known
    birthdate
    date
    Birthdate of sharer, if known
    rewards
    array
    Rewards from this conversion, only present for top-level conversion queries and webhooks and never included for conversions are embedded within reward data (Expand)
    RewardExcerpt
    id
    integer
    Friendbuy internal id for the reward
    status
    string
    One of pending, valid, or invalid
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    amount
    number
    Amount of the reward in units of the reward type
    rejected_reasons
    object
    object describing the self-referral and reward criteria that triggered the reward to be rejected
    created_at
    datetime
    Timestamp at which the reward was created
    evaluate_at
    datetime
    Timestamp at which the reward validity was evaluated
    conversion
    object
    Conversion of the reward (Expand)
    ConversionExceprtWithoutRewards
    id
    integer
    Friendbuy internal id for this conversion
    status
    string
    One of unmarked, paid, or rejected
    type
    string
    One of share, customer_personal_url, email_personal_url, or reminder_email
    campaign
    object
    Campaign for this reward (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    purchase
    object
    Purchase triggering the conversion if any (Expand)
    PurchaseExcerpt
    order_id
    string
    Order Id of the purchase
    coupon_code
    string
    Present if a coupon code was used to make the purchase
    date
    string
    Timestamp of purchase (missing time zone)
    total
    number
    Total purchase amount reported
    new_customer
    boolean
    Whether or not the purchase was reported to have been made by a new (first-time) customer, one of true, false, or unknown
    email
    string
    Email address of the purchaser if known
    ip_address
    string
    IP address
    products
    array
    List of products reported in the purchase (Expand)
    Product
    sku
    string
    Product SKU
    quantity
    number
    Number of units of the product that were purchased
    price
    number
    Amount of the order, in currency units
    customer
    object
    Customer making the purchase, if known (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    detail_uri
    string
    Friendbuy REST API resource for the conversion
    created_at
    datetime
    Conversion creation timestamp
    possible_self_referral
    boolean
    Whether the conversion may have come from an advocate using their own referral. This is done by comparing the data collected at time of a purchase to the data collected at time the share, PURL, or reminder email is generated. Note: this calculation is dependent on which fraud check settings have been enabled in the Friendbuy platform (specifically, the browser, customer id, email address, and IP address checks)
    fraud
    object
    Brief report on the presence or absence of various fraud conditions (Expand)
    FraudChecks
    same_shopper
    boolean
    Whether the same browser was used in both referral and purchase
    same_customer
    boolean
    Whether the merchant-assigned customer ids of the advocate and purchaser match
    same_email
    boolean
    Whether the email addresses of the advocate and purchaser match exactly
    same_ip_address
    boolean
    Whether the IP addresses of the advocate and purchaser match exactly
    same_ip_and_user_agent
    boolean
    Whether both the IP addresses and the user agent strings of the advocate and purchaser match exactly
    fuzzy_email
    boolean
    Whether the email addresses of the advocate and purchaser are _very_ similar
    high_sensitivity_fuzzy_email
    boolean
    Whether the email addresses of the advocate and purchaser are _loosely_ similar
    rewardDeprecated, always null
    personal_url
    object
    Present only if conversion was triggered from a PURL (Expand)
    ReferralCodeExcerpt
    referral_code
    string
    Short alphanumeric code (e.g., uxC)
    trackable_link
    string
    URI formed from the shortened domain together with the short code
    destination_url
    string
    URI in the merchant’s site that the trackable link redirects to
    referral_code_blacklisted
    boolean
    States if referral code has been invalidated from redirecting users to offer, managed within Referral Code Blacklist in the application.
    share
    object
    Present only if conversion was triggered from a share (Expand)
    ShareExcerpt
    id
    integer
    Friendbuy internal id for this share
    referral_code
    string
    Short alphanumeric code
    message
    object
    Message sent along with share (Expand)
    ShareMessage
    id
    string
    Message id assigned by facebook or twitter
    content
    string
    Text entered by the advocate
    network
    string
    Distribution channel for this share
    campaign
    object
    Campaign that is being shared (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    ip_address
    string
    IP address of the share
    newsletter_opt_in
    boolean
    Whether a newsletter opt in should take place with the share
    send_reminder
    boolean
    Whether a reminder should be sent for the share
    created_at
    datetime
    Share creation timestamp
    detail_uri
    string
    URI endpoint at which to get full details of the share
    email_recipients
    array
    JSON-formatted array of recipients for the share, present only if (1) the share is an email share and (2) the merchant is permitted to access this information (*Contact Friendbuy to inquire about the ability to access the recipient list*)
    sharer
    object
    Information for the entity making the share (Expand)
    SharerExcerpt
    name
    string
    Name of sharer, if known
    email
    string
    Email address to receive the reward, if eventually eligible
    customer
    object
    Customer information, if available at the time of share (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    facebook_friends_count
    integer
    Number of Facebook friends, if known
    twitter_followers_count
    integer
    Number of Twitter followers, if known
    birthdate
    date
    Birthdate, if known
    reminder_email
    object
    Present only if conversion was triggered from a reminder email (Expand)
    ReminderEmail
    id
    integer
    Friendbuy-assigned id for the reminder email
    customer
    string
    API link of the associated customer, if any
    widget
    string
    API link of the associated widget
    share
    string
    API link of the associated share.
    referral_link
    string
    API link of the referral link
    advocate_email_address
    string
    Email address of the advocate
    email_recipients_count
    integer
    Number of email recipients of the original share
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification
    referrer
    object
    Information about the advocate creating the conversion (Expand)
    Referrer
    customer
    object
    Present only if referral is a customer personal url or a share with a known customer (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    email
    string
    Present only if referral is an email personal url or a share with a known referring email
    name
    string
    Name of referrer, if conversion was from a share
    facebook_friends_count
    integer
    Number of Facebook friends of sharer, if known
    twitter_followers_count
    integer
    Number of Twitter followers of sharer, if known
    birthdate
    date
    Birthdate of sharer, if known

    Reward Webhook

    Example Post Body for Webhook

    {
      "id": 3181,
      "status": "invalid",
      "type": "fixed_cash",
      "amount": 10,
      "rejected_reasons": {
        "same_customer": "same customer ID detected",
        "same_email": "same email detected",
        "fuzzy_email": "similar email detected"
      },
      "created_at": "2017-01-13T19:18:38.239Z",
      "evaluate_at": "2017-01-13T19:20:38.211Z",
      "conversion": {
        "id": 121393,
        "status": "paid",
        "type": "share",
        "campaign": {
          "id": 233,
          "name": "Fall Shoe Sale",
          "published": true,
          "referral_incentive": {
            "type": "fixed_cash",
            "value": 25
          },
          "created_at": "2015-08-09T03:20:11.098230-07:00"
        },
        "purchase": {
          "order_id": "PQZ-4181",
          "coupon_code": "COUPON123456",
          "date": "2017-04-01T11:07:40.904Z",
          "total": 15.97,
          "new_customer": "true",
          "email": "adrian@example.fi",
          "ip_address": "200.1.2.3",
          "products": [
            {
              "sku": "99P88Q77R",
              "quantity": 21,
              "price": 319.99
            }
          ],
          "customer": {
            "account_id": "JAYZ",
            "id": "JAYZ",
            "email_address": "jzheng@example.mil",
            "first_name": "Jaylene",
            "last_name": "Zheng",
            "stripe_customer_id": "cus_Agg4bCEhno7A1E",
            "chargebee_customer_id": "4gkYnd21ouvW",
            "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
          }
        },
        "detail_uri": "https://developer-api.friendbuy.com/v2/conversions/121393",
        "created_at": "2016-03-01T19:12:38.239Z",
        "possible_self_referral": true,
        "fraud": {
          "same_shopper": false,
          "same_customer": false,
          "same_email": false,
          "same_ip_address": false,
          "same_ip_and_user_agent": false,
          "fuzzy_email": false,
          "high_sensitivity_fuzzy_email": false
        },
        "reward": "null",
        "personal_url": {
          "referral_code": "uxC",
          "trackable_link": "http://fbuy.me/uxC",
          "destination_url": "http://mycompany.example.com/rewards/908",
          "referral_code_blacklisted": true
        },
        "share": {
          "id": 196418,
          "referral_code": "uxC",
          "message": {
            "id": "100001965159666_428859647189537",
            "content": "This is my favorite tennis racket ever",
            "network": "facebook"
          },
          "campaign": {
            "id": 233,
            "name": "Fall Shoe Sale",
            "published": true,
            "referral_incentive": {
              "type": "fixed_cash",
              "value": 25
            },
            "created_at": "2015-08-09T03:20:11.098230-07:00"
          },
          "ip_address": "8.8.8.8",
          "newsletter_opt_in": true,
          "send_reminder": true,
          "created_at": "2017-01-13T19:18:38.239Z",
          "detail_uri": "https://developer-api.friendbuy.com/v2/shares/196418",
          "email_recipients": [
            "pele@example.br",
            "messi@example.ar"
          ],
          "sharer": {
            "name": "Taylor Gomez",
            "email": "tgo@example.net",
            "customer": {
              "account_id": "JAYZ",
              "id": "JAYZ",
              "email_address": "jzheng@example.mil",
              "first_name": "Jaylene",
              "last_name": "Zheng",
              "stripe_customer_id": "cus_Agg4bCEhno7A1E",
              "chargebee_customer_id": "4gkYnd21ouvW",
              "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
            },
            "facebook_friends_count": 987,
            "twitter_followers_count": 121393,
            "birthdate": "1989-11-09"
          }
        },
        "reminder_email": {
          "id": 377,
          "customer": "https://developer-api.friendbuy.com/v2/customers/17",
          "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
          "share": "https://developer-api.friendbuy.com/v2/shares/93813",
          "referral_link": "https://developer-api.friendbuy.com/v2/referral_links/uXc",
          "advocate_email_address": "jzheng@example.mil",
          "email_recipients_count": 100,
          "created_at": "2017-01-13T19:18:38.239Z",
          "last_modified_at": "2017-01-13T19:18:38.239Z"
        },
        "referrer": {
          "customer": {
            "account_id": "JAYZ",
            "id": "JAYZ",
            "email_address": "jzheng@example.mil",
            "first_name": "Jaylene",
            "last_name": "Zheng",
            "stripe_customer_id": "cus_Agg4bCEhno7A1E",
            "chargebee_customer_id": "4gkYnd21ouvW",
            "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
          },
          "email": "alex@example.ca",
          "name": "Taylor Gomez",
          "facebook_friends_count": 987,
          "twitter_followers_count": 121393,
          "birthdate": "1989-11-09"
        }
      }
    }
    

    A reward is an optional referral incentive that is triggered by a conversion. For each conversion that occurs, Friendbuy will check whether the widget variant associated to the referral is configured with a reward. If a reward configuration was specified, Friendbuy will then evaluate the conversion against the reward criteria and enabled fraud checks to determine if a reward should be approved. If the conversion passes all checks, the reward is approved. If not, the reward is considered to be rejected.

    The reward webhook is the preferred method for depositing credit or points into an advocate’s account in your system.

    After a reward is evaluated, Friendbuy will send a POST request to your system with data about the reward and associated conversion.

    Request Model

    RewardExcerpt
    id
    integer
    Friendbuy internal id for the reward
    status
    string
    One of pending, valid, or invalid
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    amount
    number
    Amount of the reward in units of the reward type
    rejected_reasons
    object
    object describing the self-referral and reward criteria that triggered the reward to be rejected
    created_at
    datetime
    Timestamp at which the reward was created
    evaluate_at
    datetime
    Timestamp at which the reward validity was evaluated
    conversion
    object
    Conversion of the reward (Expand)
    ConversionExceprtWithoutRewards
    id
    integer
    Friendbuy internal id for this conversion
    status
    string
    One of unmarked, paid, or rejected
    type
    string
    One of share, customer_personal_url, email_personal_url, or reminder_email
    campaign
    object
    Campaign for this reward (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    purchase
    object
    Purchase triggering the conversion if any (Expand)
    PurchaseExcerpt
    order_id
    string
    Order Id of the purchase
    coupon_code
    string
    Present if a coupon code was used to make the purchase
    date
    string
    Timestamp of purchase (missing time zone)
    total
    number
    Total purchase amount reported
    new_customer
    boolean
    Whether or not the purchase was reported to have been made by a new (first-time) customer, one of true, false, or unknown
    email
    string
    Email address of the purchaser if known
    ip_address
    string
    IP address
    products
    array
    List of products reported in the purchase (Expand)
    Product
    sku
    string
    Product SKU
    quantity
    number
    Number of units of the product that were purchased
    price
    number
    Amount of the order, in currency units
    customer
    object
    Customer making the purchase, if known (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    detail_uri
    string
    Friendbuy REST API resource for the conversion
    created_at
    datetime
    Conversion creation timestamp
    possible_self_referral
    boolean
    Whether the conversion may have come from an advocate using their own referral. This is done by comparing the data collected at time of a purchase to the data collected at time the share, PURL, or reminder email is generated. Note: this calculation is dependent on which fraud check settings have been enabled in the Friendbuy platform (specifically, the browser, customer id, email address, and IP address checks)
    fraud
    object
    Brief report on the presence or absence of various fraud conditions (Expand)
    FraudChecks
    same_shopper
    boolean
    Whether the same browser was used in both referral and purchase
    same_customer
    boolean
    Whether the merchant-assigned customer ids of the advocate and purchaser match
    same_email
    boolean
    Whether the email addresses of the advocate and purchaser match exactly
    same_ip_address
    boolean
    Whether the IP addresses of the advocate and purchaser match exactly
    same_ip_and_user_agent
    boolean
    Whether both the IP addresses and the user agent strings of the advocate and purchaser match exactly
    fuzzy_email
    boolean
    Whether the email addresses of the advocate and purchaser are _very_ similar
    high_sensitivity_fuzzy_email
    boolean
    Whether the email addresses of the advocate and purchaser are _loosely_ similar
    rewardDeprecated, always null
    personal_url
    object
    Present only if conversion was triggered from a PURL (Expand)
    ReferralCodeExcerpt
    referral_code
    string
    Short alphanumeric code (e.g., uxC)
    trackable_link
    string
    URI formed from the shortened domain together with the short code
    destination_url
    string
    URI in the merchant’s site that the trackable link redirects to
    referral_code_blacklisted
    boolean
    States if referral code has been invalidated from redirecting users to offer, managed within Referral Code Blacklist in the application.
    share
    object
    Present only if conversion was triggered from a share (Expand)
    ShareExcerpt
    id
    integer
    Friendbuy internal id for this share
    referral_code
    string
    Short alphanumeric code
    message
    object
    Message sent along with share (Expand)
    ShareMessage
    id
    string
    Message id assigned by facebook or twitter
    content
    string
    Text entered by the advocate
    network
    string
    Distribution channel for this share
    campaign
    object
    Campaign that is being shared (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    ip_address
    string
    IP address of the share
    newsletter_opt_in
    boolean
    Whether a newsletter opt in should take place with the share
    send_reminder
    boolean
    Whether a reminder should be sent for the share
    created_at
    datetime
    Share creation timestamp
    detail_uri
    string
    URI endpoint at which to get full details of the share
    email_recipients
    array
    JSON-formatted array of recipients for the share, present only if (1) the share is an email share and (2) the merchant is permitted to access this information (*Contact Friendbuy to inquire about the ability to access the recipient list*)
    sharer
    object
    Information for the entity making the share (Expand)
    SharerExcerpt
    name
    string
    Name of sharer, if known
    email
    string
    Email address to receive the reward, if eventually eligible
    customer
    object
    Customer information, if available at the time of share (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    facebook_friends_count
    integer
    Number of Facebook friends, if known
    twitter_followers_count
    integer
    Number of Twitter followers, if known
    birthdate
    date
    Birthdate, if known
    reminder_email
    object
    Present only if conversion was triggered from a reminder email (Expand)
    ReminderEmail
    id
    integer
    Friendbuy-assigned id for the reminder email
    customer
    string
    API link of the associated customer, if any
    widget
    string
    API link of the associated widget
    share
    string
    API link of the associated share.
    referral_link
    string
    API link of the referral link
    advocate_email_address
    string
    Email address of the advocate
    email_recipients_count
    integer
    Number of email recipients of the original share
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification
    referrer
    object
    Information about the advocate creating the conversion (Expand)
    Referrer
    customer
    object
    Present only if referral is a customer personal url or a share with a known customer (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    email
    string
    Present only if referral is an email personal url or a share with a known referring email
    name
    string
    Name of referrer, if conversion was from a share
    facebook_friends_count
    integer
    Number of Facebook friends of sharer, if known
    twitter_followers_count
    integer
    Number of Twitter followers of sharer, if known
    birthdate
    date
    Birthdate of sharer, if known

    Unsubscribe Webhook

    Example Post Body for Webhook

    {
      "id": 14232,
      "email": "rapinoe@example.us",
      "source": "share",
      "ip_address": "8.8.8.8",
      "created_at": "2019-01-13T19:18:38.239Z",
      "campaign": {
        "id": 233,
        "name": "Fall Shoe Sale",
        "published": true,
        "referral_incentive": {
          "type": "fixed_cash",
          "value": 25
        },
        "created_at": "2015-08-09T03:20:11.098230-07:00"
      },
      "share": {
        "id": 196418,
        "message": "Check these out",
        "channel": "facebook",
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "ip_address": "8.8.8.8",
        "referral_link": "https://developer-api.friendbuy.com/v2/referral_links/uXc",
        "newsletter_opt_in": true,
        "send_reminder": true,
        "customer": "https://developer-api.friendbuy.com/v2/customers/17",
        "reward_email_address": "alice@example.org",
        "email_recipients": [
          "pele@example.br",
          "messi@example.ar"
        ],
        "link_parameters": "{\"utm_medium\": \"referral\", \"utm_source\": \"Friendbuy\"}",
        "created_at": "2017-01-13T19:18:38.239Z",
        "last_modified_at": "2017-01-13T19:18:38.239Z"
      }
    }
    

    An unsubscrive occurs when (1) a user clicks on the unsubscribe link included in all share emails, (2) an email is included in an opt-out file uploaded to the Friendbuy platform or through the REST API, or (3) a user clicks on the unsubscribe link contained in all promotional communication emails.

    The unsubscribe webhook can be used to update your master opt-out list with all users who unsubscribe from friendbuy emails.

    After a successful unsubscribe, Friendbuy will send a POST request to your system containing data about the unsubscribe.

    Request Model

    UnsubscribeExcerpt
    id
    integer
    Friendbuy internal id for the unsubscribe event
    email
    string
    The email address that has unsubscribed
    source
    string
    The source of the unsubscribe. One of 'share', 'upload', or 'communication_promotional'
    ip_address
    string
    IP address associated with the unsubscribe
    created_at
    datetime
    Timestamp at which the unsubscribe was created
    campaign
    object
    The campaign associated with the unsubscribe. Only present if the source is 'share' (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    share
    object
    The share associated with the unsubscrib, if any. Only present if the source is 'share' (Expand)
    Share
    id
    integer
    Friendbuy internal id for this share
    message
    string
    Message sent along with share
    channel
    string
    One of facebook, twitter, messenger, or email
    widget
    string
    API link of the associated widget
    ip_address
    string
    IP address of the share
    referral_link
    string
    API link of the referral link
    newsletter_opt_in
    boolean
    Whether a newsletter opt in should take place with the share
    send_reminder
    boolean
    Whether a reminder should be sent for the share
    customer
    string
    API link of the associated customer, if any
    reward_email_address
    string
    Email address of the advocate
    email_recipients
    array
    Array of recipients for the share, present only if (1) the share is an email share and (2) the merchant is permitted to access this information (Contact Friendbuy to inquire about the ability to access the recipient list)
    link_parameters
    string
    Link parameters set on the referral code
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification

    Client API Integrations

    Friendbuy can integrate with your system to request supplemental instructions in real time prior to sending shares or approving rewards.

    Email Recipient Authorization

    Example Request

    [
      "messi@example.ar",
      "pele@example.br",
      "zico@example.br",
      "maradonna@example.ar"
    ]
    

    Example Response

    [
      "pele@example.br",
      "maradonna@example.ar"
    ]
    

    Before sending a email share, Friendbuy can check your system to see if the email addresses listed in the share are authorized to receive emails from your company. This can be used to supplement the Friendbuy-maintained opt-out list. Friendbuy’s list contains email addresses that have opted out through a previous shared email, through an upload of email addresses in the Friendbuy platform, or via the REST API.

    To enable this feature, provide the URL of your HTTPS POST endpoint to your Friendbuy Customer Success Manager.

    If enabled, the integration works as follows:

    1. Using your provided endpoint, Friendbuy will request real-time authorization to share with the addresses entered by an advocate into a Referral and Sharing widget. The intended recipient email addresses are contained in the HTTPS POST body as a JSON string array.
    2. Your API will repsond with the email addresses that are authorized to receive emails. In the case of an opt-out list, your API should return the email addresses that are not in the opt-out list.
    3. Friendbuy will send share emails to all addresses returned in your response. Addresses in the request that are not included in the response will be excluded from the share.
    4. A response with status code 200 containing a JSON array of acceptable addresses is expected. Retries will be made according to the Friendbuy retry protocol.

    Request Headers

    Header Description
    X-FRIENDBUY-SIGNATURE Request body signature

    Custom Reward Validation

    Example Post Body

    {
      "id": 121393,
      "status": "paid",
      "type": "share",
      "campaign": {
        "id": 233,
        "name": "Fall Shoe Sale",
        "published": true,
        "referral_incentive": {
          "type": "fixed_cash",
          "value": 25
        },
        "created_at": "2015-08-09T03:20:11.098230-07:00"
      },
      "purchase": {
        "order_id": "PQZ-4181",
        "coupon_code": "COUPON123456",
        "date": "2017-04-01T11:07:40.904Z",
        "total": 15.97,
        "new_customer": "true",
        "email": "adrian@example.fi",
        "ip_address": "200.1.2.3",
        "products": [
          {
            "sku": "99P88Q77R",
            "quantity": 21,
            "price": 319.99
          }
        ],
        "customer": {
          "account_id": "JAYZ",
          "id": "JAYZ",
          "email_address": "jzheng@example.mil",
          "first_name": "Jaylene",
          "last_name": "Zheng",
          "stripe_customer_id": "cus_Agg4bCEhno7A1E",
          "chargebee_customer_id": "4gkYnd21ouvW",
          "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
        }
      },
      "detail_uri": "https://developer-api.friendbuy.com/v2/conversions/121393",
      "created_at": "2016-03-01T19:12:38.239Z",
      "possible_self_referral": true,
      "fraud": {
        "same_shopper": false,
        "same_customer": false,
        "same_email": false,
        "same_ip_address": false,
        "same_ip_and_user_agent": false,
        "fuzzy_email": false,
        "high_sensitivity_fuzzy_email": false
      },
      "reward": "null",
      "personal_url": {
        "referral_code": "uxC",
        "trackable_link": "http://fbuy.me/uxC",
        "destination_url": "http://mycompany.example.com/rewards/908",
        "referral_code_blacklisted": true
      },
      "share": {
        "id": 196418,
        "referral_code": "uxC",
        "message": {
          "id": "100001965159666_428859647189537",
          "content": "This is my favorite tennis racket ever",
          "network": "facebook"
        },
        "campaign": {
          "id": 233,
          "name": "Fall Shoe Sale",
          "published": true,
          "referral_incentive": {
            "type": "fixed_cash",
            "value": 25
          },
          "created_at": "2015-08-09T03:20:11.098230-07:00"
        },
        "ip_address": "8.8.8.8",
        "newsletter_opt_in": true,
        "send_reminder": true,
        "created_at": "2017-01-13T19:18:38.239Z",
        "detail_uri": "https://developer-api.friendbuy.com/v2/shares/196418",
        "email_recipients": [
          "pele@example.br",
          "messi@example.ar"
        ],
        "sharer": {
          "name": "Taylor Gomez",
          "email": "tgo@example.net",
          "customer": {
            "account_id": "JAYZ",
            "id": "JAYZ",
            "email_address": "jzheng@example.mil",
            "first_name": "Jaylene",
            "last_name": "Zheng",
            "stripe_customer_id": "cus_Agg4bCEhno7A1E",
            "chargebee_customer_id": "4gkYnd21ouvW",
            "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1",
            "created_at": "2013-02-02T02:02:02.222220",
            "recent_shares": [
              {
                "id": 196418,
                "referral_code": "uxC",
                "message": {
                  "id": "100001965159666_428859647189537",
                  "content": "This is my favorite tennis racket ever",
                  "network": "facebook"
                },
                "campaign": {
                  "id": 233,
                  "name": "Fall Shoe Sale",
                  "published": true,
                  "referral_incentive": {
                    "type": "fixed_cash",
                    "value": 25
                  },
                  "created_at": "2015-08-09T03:20:11.098230-07:00"
                },
                "ip_address": "8.8.8.8",
                "newsletter_opt_in": true,
                "send_reminder": true,
                "created_at": "2017-01-13T19:18:38.239Z",
                "detail_uri": "https://developer-api.friendbuy.com/v2/shares/196418",
                "email_recipients": [
                  "pele@example.br",
                  "messi@example.ar"
                ],
                "sharer": {
                  "name": "Taylor Gomez",
                  "email": "tgo@example.net",
                  "customer": {
                    "account_id": "JAYZ",
                    "id": "JAYZ",
                    "email_address": "jzheng@example.mil",
                    "first_name": "Jaylene",
                    "last_name": "Zheng",
                    "stripe_customer_id": "cus_Agg4bCEhno7A1E",
                    "chargebee_customer_id": "4gkYnd21ouvW",
                    "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
                  },
                  "facebook_friends_count": 987,
                  "twitter_followers_count": 121393,
                  "birthdate": "1989-11-09"
                }
              }
            ],
            "recent_referral_codes": [
              {
                "referral_code": "uxC",
                "trackable_link": "http://fbuy.me/uxC",
                "destination_url": "http://mycompany.example.com/rewards/908",
                "referral_code_blacklisted": true
              }
            ]
          },
          "facebook_friends_count": 987,
          "twitter_followers_count": 121393,
          "birthdate": "1989-11-09",
          "facebook_profile": {
            "facebook_id": "100001724970193",
            "name": "Taylor Gomez",
            "first_name": "Taylor",
            "last_name": "Gomez",
            "email_address": "tgo@example.net",
            "gender": "female",
            "locale": "es_MX",
            "link": "http://www.facebook.com/100001724970193",
            "timezone": -7,
            "verified": true,
            "birthday": "1989-11-09T00:00:00.000Z",
            "picture_url": "http://pictures.example.org/8abdjw87fe677lko",
            "friends_count": 75025
          },
          "twitter_profile": {
            "twitter_id": "308061521170129",
            "name": "Taylor Gomez",
            "screen_name": "taygomz17711",
            "time_zone": "America/Mexico_City",
            "bio": "Rabblerouser, marathon runner, pole vaulter, senator",
            "homepage": "senate.example.mx/taylor_gomez",
            "location": "Antarctica",
            "language": "es",
            "utc_offset": -18000,
            "statuses_count": 89,
            "friends_count": 55,
            "followers_count": 75025,
            "favourites_count": 1597,
            "listed_count": 13,
            "is_translator": false,
            "contributors_enabled": true,
            "verified": true,
            "geo_enabled": true,
            "protected": false,
            "picture_url": "http://pbs.twimg.com/profile_images/601898989899999900/DzBmLB0Y.png"
          }
        },
        "purchase": {
          "order_id": "PQZ-4181",
          "coupon_code": "COUPON123456",
          "date": "2017-04-01T11:07:40.904Z",
          "total": 15.97,
          "new_customer": "true",
          "email": "adrian@example.fi",
          "ip_address": "200.1.2.3",
          "products": [
            {
              "sku": "99P88Q77R",
              "quantity": 21,
              "price": 319.99
            }
          ],
          "customer": {
            "account_id": "JAYZ",
            "id": "JAYZ",
            "email_address": "jzheng@example.mil",
            "first_name": "Jaylene",
            "last_name": "Zheng",
            "stripe_customer_id": "cus_Agg4bCEhno7A1E",
            "chargebee_customer_id": "4gkYnd21ouvW",
            "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1",
            "created_at": "2013-02-02T02:02:02.222220",
            "recent_shares": [
              {
                "id": 196418,
                "referral_code": "uxC",
                "message": {
                  "id": "100001965159666_428859647189537",
                  "content": "This is my favorite tennis racket ever",
                  "network": "facebook"
                },
                "campaign": {
                  "id": 233,
                  "name": "Fall Shoe Sale",
                  "published": true,
                  "referral_incentive": {
                    "type": "fixed_cash",
                    "value": 25
                  },
                  "created_at": "2015-08-09T03:20:11.098230-07:00"
                },
                "ip_address": "8.8.8.8",
                "newsletter_opt_in": true,
                "send_reminder": true,
                "created_at": "2017-01-13T19:18:38.239Z",
                "detail_uri": "https://developer-api.friendbuy.com/v2/shares/196418",
                "email_recipients": [
                  "pele@example.br",
                  "messi@example.ar"
                ],
                "sharer": {
                  "name": "Taylor Gomez",
                  "email": "tgo@example.net",
                  "customer": {
                    "account_id": "JAYZ",
                    "id": "JAYZ",
                    "email_address": "jzheng@example.mil",
                    "first_name": "Jaylene",
                    "last_name": "Zheng",
                    "stripe_customer_id": "cus_Agg4bCEhno7A1E",
                    "chargebee_customer_id": "4gkYnd21ouvW",
                    "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
                  },
                  "facebook_friends_count": 987,
                  "twitter_followers_count": 121393,
                  "birthdate": "1989-11-09"
                }
              }
            ],
            "recent_referral_codes": [
              {
                "referral_code": "uxC",
                "trackable_link": "http://fbuy.me/uxC",
                "destination_url": "http://mycompany.example.com/rewards/908",
                "referral_code_blacklisted": true
              }
            ]
          }
        }
      },
      "reminder_email": {
        "id": 377,
        "customer": "https://developer-api.friendbuy.com/v2/customers/17",
        "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
        "share": "https://developer-api.friendbuy.com/v2/shares/93813",
        "referral_link": "https://developer-api.friendbuy.com/v2/referral_links/uXc",
        "advocate_email_address": "jzheng@example.mil",
        "email_recipients_count": 100,
        "created_at": "2017-01-13T19:18:38.239Z",
        "last_modified_at": "2017-01-13T19:18:38.239Z"
      },
      "referrer": {
        "customer": {
          "account_id": "JAYZ",
          "id": "JAYZ",
          "email_address": "jzheng@example.mil",
          "first_name": "Jaylene",
          "last_name": "Zheng",
          "stripe_customer_id": "cus_Agg4bCEhno7A1E",
          "chargebee_customer_id": "4gkYnd21ouvW",
          "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
        },
        "email": "alex@example.ca",
        "name": "Taylor Gomez",
        "facebook_friends_count": 987,
        "twitter_followers_count": 121393,
        "birthdate": "1989-11-09"
      },
      "rewards": [
        {
          "id": 3181,
          "status": "invalid",
          "type": "fixed_cash",
          "amount": 10,
          "rejected_reasons": {
            "same_customer": "same customer ID detected",
            "same_email": "same email detected",
            "fuzzy_email": "similar email detected"
          },
          "created_at": "2017-01-13T19:18:38.239Z",
          "evaluate_at": "2017-01-13T19:20:38.211Z",
          "conversion": {
            "id": 121393,
            "status": "paid",
            "type": "share",
            "campaign": {
              "id": 233,
              "name": "Fall Shoe Sale",
              "published": true,
              "referral_incentive": {
                "type": "fixed_cash",
                "value": 25
              },
              "created_at": "2015-08-09T03:20:11.098230-07:00"
            },
            "purchase": {
              "order_id": "PQZ-4181",
              "coupon_code": "COUPON123456",
              "date": "2017-04-01T11:07:40.904Z",
              "total": 15.97,
              "new_customer": "true",
              "email": "adrian@example.fi",
              "ip_address": "200.1.2.3",
              "products": [
                {
                  "sku": "99P88Q77R",
                  "quantity": 21,
                  "price": 319.99
                }
              ],
              "customer": {
                "account_id": "JAYZ",
                "id": "JAYZ",
                "email_address": "jzheng@example.mil",
                "first_name": "Jaylene",
                "last_name": "Zheng",
                "stripe_customer_id": "cus_Agg4bCEhno7A1E",
                "chargebee_customer_id": "4gkYnd21ouvW",
                "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
              }
            },
            "detail_uri": "https://developer-api.friendbuy.com/v2/conversions/121393",
            "created_at": "2016-03-01T19:12:38.239Z",
            "possible_self_referral": true,
            "fraud": {
              "same_shopper": false,
              "same_customer": false,
              "same_email": false,
              "same_ip_address": false,
              "same_ip_and_user_agent": false,
              "fuzzy_email": false,
              "high_sensitivity_fuzzy_email": false
            },
            "reward": "null",
            "personal_url": {
              "referral_code": "uxC",
              "trackable_link": "http://fbuy.me/uxC",
              "destination_url": "http://mycompany.example.com/rewards/908",
              "referral_code_blacklisted": true
            },
            "share": {
              "id": 196418,
              "referral_code": "uxC",
              "message": {
                "id": "100001965159666_428859647189537",
                "content": "This is my favorite tennis racket ever",
                "network": "facebook"
              },
              "campaign": {
                "id": 233,
                "name": "Fall Shoe Sale",
                "published": true,
                "referral_incentive": {
                  "type": "fixed_cash",
                  "value": 25
                },
                "created_at": "2015-08-09T03:20:11.098230-07:00"
              },
              "ip_address": "8.8.8.8",
              "newsletter_opt_in": true,
              "send_reminder": true,
              "created_at": "2017-01-13T19:18:38.239Z",
              "detail_uri": "https://developer-api.friendbuy.com/v2/shares/196418",
              "email_recipients": [
                "pele@example.br",
                "messi@example.ar"
              ],
              "sharer": {
                "name": "Taylor Gomez",
                "email": "tgo@example.net",
                "customer": {
                  "account_id": "JAYZ",
                  "id": "JAYZ",
                  "email_address": "jzheng@example.mil",
                  "first_name": "Jaylene",
                  "last_name": "Zheng",
                  "stripe_customer_id": "cus_Agg4bCEhno7A1E",
                  "chargebee_customer_id": "4gkYnd21ouvW",
                  "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
                },
                "facebook_friends_count": 987,
                "twitter_followers_count": 121393,
                "birthdate": "1989-11-09"
              }
            },
            "reminder_email": {
              "id": 377,
              "customer": "https://developer-api.friendbuy.com/v2/customers/17",
              "widget": "https://developer-api.friendbuy.com/v2/widgets/55",
              "share": "https://developer-api.friendbuy.com/v2/shares/93813",
              "referral_link": "https://developer-api.friendbuy.com/v2/referral_links/uXc",
              "advocate_email_address": "jzheng@example.mil",
              "email_recipients_count": 100,
              "created_at": "2017-01-13T19:18:38.239Z",
              "last_modified_at": "2017-01-13T19:18:38.239Z"
            },
            "referrer": {
              "customer": {
                "account_id": "JAYZ",
                "id": "JAYZ",
                "email_address": "jzheng@example.mil",
                "first_name": "Jaylene",
                "last_name": "Zheng",
                "stripe_customer_id": "cus_Agg4bCEhno7A1E",
                "chargebee_customer_id": "4gkYnd21ouvW",
                "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
              },
              "email": "alex@example.ca",
              "name": "Taylor Gomez",
              "facebook_friends_count": 987,
              "twitter_followers_count": 121393,
              "birthdate": "1989-11-09"
            }
          }
        }
      ]
    }
    

    The custom reward validation integration allows you to add custom criteria to determine whether or not Friendbuy should fulfill a reward to an advocate. Example use cases for this integration include checking for returns or cancellations, checking that a referred friend has remained a customer after a trial period, or performing additional fraud checks. It is best used with a reward delay, which is configured for a Referral and Sharing widget. The reward delay will postpone the processing of a reward until a set number of days has passed, at which point the reward will be evaluated against criteria set in the Referral and Sharing widget.

    To enable the feature, enter the validation URL in the Reward Criteria section of the appropriate Referral and Sharing widgets.

    When enabled, the integration works as follows:

    1. After Friendbuy has evaluated the reward against the preconfigured reward criteria and fraud checks, and the specified reward delay period has passed, we will request validation for a pending reward with a signed HTTPS POST request to your designated endpoint.
    2. The request body will include details about the conversion event, such as the referrer, purchase date, order id, and more.
    3. An HTTP response code between 200 and 299 inclusive will validate the reward and instruct Friendbuy to issue the reward. Any other status code will indicate the reward is invalid. Retries are made according to the Friendbuy retry protocol. If no successful response is received within the 24-hour retry period, the reward will be considered invalid.

    Request Headers

    Header Description
    X-FRIENDBUY-SIGNATURE-V2 Request body signature

    Request Model

    Conversion
    id
    integer
    Friendbuy internal id for this conversion
    status
    string
    One of unmarked, paid, or rejected
    type
    string
    One of share, customer_personal_url, email_personal_url, or reminder_email
    campaign
    object
    Campaign for this reward (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    purchase
    object
    Purchase triggering the conversion if any (Expand)
    PurchaseExcerpt
    order_id
    string
    Order Id of the purchase
    coupon_code
    string
    Present if a coupon code was used to make the purchase
    date
    string
    Timestamp of purchase (missing time zone)
    total
    number
    Total purchase amount reported
    new_customer
    boolean
    Whether or not the purchase was reported to have been made by a new (first-time) customer, one of true, false, or unknown
    email
    string
    Email address of the purchaser if known
    ip_address
    string
    IP address
    products
    array
    List of products reported in the purchase (Expand)
    Product
    sku
    string
    Product SKU
    quantity
    number
    Number of units of the product that were purchased
    price
    number
    Amount of the order, in currency units
    customer
    object
    Customer making the purchase, if known (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    detail_uri
    string
    Friendbuy REST API resource for the conversion
    created_at
    datetime
    Conversion creation timestamp
    possible_self_referral
    boolean
    Whether the conversion may have come from an advocate using their own referral. This is done by comparing the data collected at time of a purchase to the data collected at time the share, PURL, or reminder email is generated. Note: this calculation is dependent on which fraud check settings have been enabled in the Friendbuy platform (specifically, the browser, customer id, email address, and IP address checks)
    fraud
    object
    Brief report on the presence or absence of various fraud conditions (Expand)
    FraudChecks
    same_shopper
    boolean
    Whether the same browser was used in both referral and purchase
    same_customer
    boolean
    Whether the merchant-assigned customer ids of the advocate and purchaser match
    same_email
    boolean
    Whether the email addresses of the advocate and purchaser match exactly
    same_ip_address
    boolean
    Whether the IP addresses of the advocate and purchaser match exactly
    same_ip_and_user_agent
    boolean
    Whether both the IP addresses and the user agent strings of the advocate and purchaser match exactly
    fuzzy_email
    boolean
    Whether the email addresses of the advocate and purchaser are _very_ similar
    high_sensitivity_fuzzy_email
    boolean
    Whether the email addresses of the advocate and purchaser are _loosely_ similar
    rewardDeprecated, always null
    personal_url
    object
    Present only if conversion was triggered from a PURL (Expand)
    ReferralCodeExcerpt
    referral_code
    string
    Short alphanumeric code (e.g., uxC)
    trackable_link
    string
    URI formed from the shortened domain together with the short code
    destination_url
    string
    URI in the merchant’s site that the trackable link redirects to
    referral_code_blacklisted
    boolean
    States if referral code has been invalidated from redirecting users to offer, managed within Referral Code Blacklist in the application.
    share
    object
    Present only if conversion was triggered from a share (Expand)
    Share
    id
    integer
    Friendbuy internal id for this share
    referral_code
    string
    Short alphanumeric code
    message
    object
    Message sent along with share (Expand)
    ShareMessage
    id
    string
    Message id assigned by facebook or twitter
    content
    string
    Text entered by the advocate
    network
    string
    Distribution channel for this share
    campaign
    object
    Campaign that is being shared (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    ip_address
    string
    IP address of the share
    newsletter_opt_in
    boolean
    Whether a newsletter opt in should take place with the share
    send_reminder
    boolean
    Whether a reminder should be sent for the share
    created_at
    datetime
    Share creation timestamp
    detail_uri
    string
    URI endpoint at which to get full details of the share
    email_recipients
    array
    JSON-formatted array of recipients for the share, present only if (1) the share is an email share and (2) the merchant is permitted to access this information (*Contact Friendbuy to inquire about the ability to access the recipient list*)
    sharer
    object
    Information for the entity making the share (Expand)
    Sharer
    name
    string
    Name of sharer, if known
    email
    string
    Email address to receive the reward, if eventually eligible
    customer
    object
    Customer information, if available at the time of share (Expand)
    Customer
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    created_at
    datetime
    Timestamp at which Friendbuy created the customer record (missing time zone)
    recent_shares
    array
    Array of the customer’s recent shares (Expand)
    ShareExcerpt
    id
    integer
    Friendbuy internal id for this share
    referral_code
    string
    Short alphanumeric code
    message
    object
    Message sent along with share (Expand)
    ShareMessage
    id
    string
    Message id assigned by facebook or twitter
    content
    string
    Text entered by the advocate
    network
    string
    Distribution channel for this share
    campaign
    object
    Campaign that is being shared (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    ip_address
    string
    IP address of the share
    newsletter_opt_in
    boolean
    Whether a newsletter opt in should take place with the share
    send_reminder
    boolean
    Whether a reminder should be sent for the share
    created_at
    datetime
    Share creation timestamp
    detail_uri
    string
    URI endpoint at which to get full details of the share
    email_recipients
    array
    JSON-formatted array of recipients for the share, present only if (1) the share is an email share and (2) the merchant is permitted to access this information (*Contact Friendbuy to inquire about the ability to access the recipient list*)
    sharer
    object
    Information for the entity making the share (Expand)
    SharerExcerpt
    name
    string
    Name of sharer, if known
    email
    string
    Email address to receive the reward, if eventually eligible
    customer
    object
    Customer information, if available at the time of share (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    facebook_friends_count
    integer
    Number of Facebook friends, if known
    twitter_followers_count
    integer
    Number of Twitter followers, if known
    birthdate
    date
    Birthdate, if known
    recent_referral_codes
    array
    Array of the customer’s recent referral codes (Expand)
    ReferralCodeExcerpt
    referral_code
    string
    Short alphanumeric code (e.g., uxC)
    trackable_link
    string
    URI formed from the shortened domain together with the short code
    destination_url
    string
    URI in the merchant’s site that the trackable link redirects to
    referral_code_blacklisted
    boolean
    States if referral code has been invalidated from redirecting users to offer, managed within Referral Code Blacklist in the application.
    facebook_friends_count
    integer
    Number of Facebook friends, if known
    twitter_followers_count
    integer
    Number of Twitter followers, if known
    birthdate
    date
    Birthdate, if known
    facebook_profile
    object
    Facebook profile data (Expand)
    FacebookProfile
    facebook_id
    string
    Id known to Facebook
    name
    string
    Name known to Facebook
    first_name
    string
    First name
    last_name
    string
    Last Name
    email_address
    string
    Email stored in Facebook profile
    gender
    string
    Facebook-captured gender information
    locale
    string
    Knwon locale
    link
    string
    Facebook link
    timezone
    integer
    Time zone offset
    verified
    boolean
    Whether the profile is marked as verified by Facebook
    birthday
    datetime
    Birthdate reported to Facebook
    picture_url
    string
    URL of facebook picture
    friends_count
    integer
    Number of Facebook friends
    twitter_profile
    object
    Twitter profile data (Expand)
    TwitterProfile
    twitter_id
    string
    Id at Twitter
    name
    string
    Twitter name
    screen_name
    string
    Twitter screen name
    time_zone
    string
    Time zone
    bio
    string
    Twitter bio
    homepage
    string
    Home page
    location
    string
    User-defined location for the Twitter profile
    language
    string
    Language reported to Twitter
    utc_offset
    integer
    Offset from UTC in seconds
    statuses_count
    integer
    Number of tweets, including retweets
    friends_count
    integer
    Number of friends
    followers_count
    integer
    Number of followers
    favourites_count
    integer
    Number of favorites
    listed_count
    integer
    The number of public lists that this account is a member of
    is_translator
    boolean
    Whether the user is a participant in Twitter’s translator community
    contributors_enabled
    boolean
    Whether contributors are enabled
    verified
    boolean
    Whether the Twitter account is verified
    geo_enabled
    boolean
    Whether the account is geo enabled
    protected
    boolean
    Whether the Twitter user has chosen to protect the tweets
    picture_url
    string
    URL for the Twitter picture
    purchase
    object
    Purchase (Expand)
    Purchase
    order_id
    string
    Order Id of the purchase
    coupon_code
    string
    Present if a coupon code was used to make the purchase
    date
    string
    Timestamp of purchase (missing time zone)
    total
    number
    Total purchase amount reported
    new_customer
    boolean
    Whether or not the purchase was reported to have been made by a new (first-time) customer, one of true, false, or unknown
    email
    string
    Email address of the purchaser if known
    ip_address
    string
    IP address
    products
    array
    List of products reported in the purchase (Expand)
    Product
    sku
    string
    Product SKU
    quantity
    number
    Number of units of the product that were purchased
    price
    number
    Amount of the order, in currency units
    customer
    object
    Customer making the purchase, if known (Expand)
    Customer
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    created_at
    datetime
    Timestamp at which Friendbuy created the customer record (missing time zone)
    recent_shares
    array
    Array of the customer’s recent shares (Expand)
    ShareExcerpt
    id
    integer
    Friendbuy internal id for this share
    referral_code
    string
    Short alphanumeric code
    message
    object
    Message sent along with share (Expand)
    ShareMessage
    id
    string
    Message id assigned by facebook or twitter
    content
    string
    Text entered by the advocate
    network
    string
    Distribution channel for this share
    campaign
    object
    Campaign that is being shared (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    ip_address
    string
    IP address of the share
    newsletter_opt_in
    boolean
    Whether a newsletter opt in should take place with the share
    send_reminder
    boolean
    Whether a reminder should be sent for the share
    created_at
    datetime
    Share creation timestamp
    detail_uri
    string
    URI endpoint at which to get full details of the share
    email_recipients
    array
    JSON-formatted array of recipients for the share, present only if (1) the share is an email share and (2) the merchant is permitted to access this information (*Contact Friendbuy to inquire about the ability to access the recipient list*)
    sharer
    object
    Information for the entity making the share (Expand)
    SharerExcerpt
    name
    string
    Name of sharer, if known
    email
    string
    Email address to receive the reward, if eventually eligible
    customer
    object
    Customer information, if available at the time of share (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    facebook_friends_count
    integer
    Number of Facebook friends, if known
    twitter_followers_count
    integer
    Number of Twitter followers, if known
    birthdate
    date
    Birthdate, if known
    recent_referral_codes
    array
    Array of the customer’s recent referral codes (Expand)
    ReferralCodeExcerpt
    referral_code
    string
    Short alphanumeric code (e.g., uxC)
    trackable_link
    string
    URI formed from the shortened domain together with the short code
    destination_url
    string
    URI in the merchant’s site that the trackable link redirects to
    referral_code_blacklisted
    boolean
    States if referral code has been invalidated from redirecting users to offer, managed within Referral Code Blacklist in the application.
    reminder_email
    object
    Present only if conversion was triggered from a reminder email (Expand)
    ReminderEmail
    id
    integer
    Friendbuy-assigned id for the reminder email
    customer
    string
    API link of the associated customer, if any
    widget
    string
    API link of the associated widget
    share
    string
    API link of the associated share.
    referral_link
    string
    API link of the referral link
    advocate_email_address
    string
    Email address of the advocate
    email_recipients_count
    integer
    Number of email recipients of the original share
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification
    referrer
    object
    Information about the advocate creating the conversion (Expand)
    Referrer
    customer
    object
    Present only if referral is a customer personal url or a share with a known customer (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    email
    string
    Present only if referral is an email personal url or a share with a known referring email
    name
    string
    Name of referrer, if conversion was from a share
    facebook_friends_count
    integer
    Number of Facebook friends of sharer, if known
    twitter_followers_count
    integer
    Number of Twitter followers of sharer, if known
    birthdate
    date
    Birthdate of sharer, if known
    rewards
    array
    Rewards from this conversion, only present for top-level conversion queries and webhooks and never included for conversions are embedded within reward data (Expand)
    RewardExcerpt
    id
    integer
    Friendbuy internal id for the reward
    status
    string
    One of pending, valid, or invalid
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    amount
    number
    Amount of the reward in units of the reward type
    rejected_reasons
    object
    object describing the self-referral and reward criteria that triggered the reward to be rejected
    created_at
    datetime
    Timestamp at which the reward was created
    evaluate_at
    datetime
    Timestamp at which the reward validity was evaluated
    conversion
    object
    Conversion of the reward (Expand)
    ConversionExceprtWithoutRewards
    id
    integer
    Friendbuy internal id for this conversion
    status
    string
    One of unmarked, paid, or rejected
    type
    string
    One of share, customer_personal_url, email_personal_url, or reminder_email
    campaign
    object
    Campaign for this reward (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    purchase
    object
    Purchase triggering the conversion if any (Expand)
    PurchaseExcerpt
    order_id
    string
    Order Id of the purchase
    coupon_code
    string
    Present if a coupon code was used to make the purchase
    date
    string
    Timestamp of purchase (missing time zone)
    total
    number
    Total purchase amount reported
    new_customer
    boolean
    Whether or not the purchase was reported to have been made by a new (first-time) customer, one of true, false, or unknown
    email
    string
    Email address of the purchaser if known
    ip_address
    string
    IP address
    products
    array
    List of products reported in the purchase (Expand)
    Product
    sku
    string
    Product SKU
    quantity
    number
    Number of units of the product that were purchased
    price
    number
    Amount of the order, in currency units
    customer
    object
    Customer making the purchase, if known (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    detail_uri
    string
    Friendbuy REST API resource for the conversion
    created_at
    datetime
    Conversion creation timestamp
    possible_self_referral
    boolean
    Whether the conversion may have come from an advocate using their own referral. This is done by comparing the data collected at time of a purchase to the data collected at time the share, PURL, or reminder email is generated. Note: this calculation is dependent on which fraud check settings have been enabled in the Friendbuy platform (specifically, the browser, customer id, email address, and IP address checks)
    fraud
    object
    Brief report on the presence or absence of various fraud conditions (Expand)
    FraudChecks
    same_shopper
    boolean
    Whether the same browser was used in both referral and purchase
    same_customer
    boolean
    Whether the merchant-assigned customer ids of the advocate and purchaser match
    same_email
    boolean
    Whether the email addresses of the advocate and purchaser match exactly
    same_ip_address
    boolean
    Whether the IP addresses of the advocate and purchaser match exactly
    same_ip_and_user_agent
    boolean
    Whether both the IP addresses and the user agent strings of the advocate and purchaser match exactly
    fuzzy_email
    boolean
    Whether the email addresses of the advocate and purchaser are _very_ similar
    high_sensitivity_fuzzy_email
    boolean
    Whether the email addresses of the advocate and purchaser are _loosely_ similar
    rewardDeprecated, always null
    personal_url
    object
    Present only if conversion was triggered from a PURL (Expand)
    ReferralCodeExcerpt
    referral_code
    string
    Short alphanumeric code (e.g., uxC)
    trackable_link
    string
    URI formed from the shortened domain together with the short code
    destination_url
    string
    URI in the merchant’s site that the trackable link redirects to
    referral_code_blacklisted
    boolean
    States if referral code has been invalidated from redirecting users to offer, managed within Referral Code Blacklist in the application.
    share
    object
    Present only if conversion was triggered from a share (Expand)
    ShareExcerpt
    id
    integer
    Friendbuy internal id for this share
    referral_code
    string
    Short alphanumeric code
    message
    object
    Message sent along with share (Expand)
    ShareMessage
    id
    string
    Message id assigned by facebook or twitter
    content
    string
    Text entered by the advocate
    network
    string
    Distribution channel for this share
    campaign
    object
    Campaign that is being shared (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    ip_address
    string
    IP address of the share
    newsletter_opt_in
    boolean
    Whether a newsletter opt in should take place with the share
    send_reminder
    boolean
    Whether a reminder should be sent for the share
    created_at
    datetime
    Share creation timestamp
    detail_uri
    string
    URI endpoint at which to get full details of the share
    email_recipients
    array
    JSON-formatted array of recipients for the share, present only if (1) the share is an email share and (2) the merchant is permitted to access this information (*Contact Friendbuy to inquire about the ability to access the recipient list*)
    sharer
    object
    Information for the entity making the share (Expand)
    SharerExcerpt
    name
    string
    Name of sharer, if known
    email
    string
    Email address to receive the reward, if eventually eligible
    customer
    object
    Customer information, if available at the time of share (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    facebook_friends_count
    integer
    Number of Facebook friends, if known
    twitter_followers_count
    integer
    Number of Twitter followers, if known
    birthdate
    date
    Birthdate, if known
    reminder_email
    object
    Present only if conversion was triggered from a reminder email (Expand)
    ReminderEmail
    id
    integer
    Friendbuy-assigned id for the reminder email
    customer
    string
    API link of the associated customer, if any
    widget
    string
    API link of the associated widget
    share
    string
    API link of the associated share.
    referral_link
    string
    API link of the referral link
    advocate_email_address
    string
    Email address of the advocate
    email_recipients_count
    integer
    Number of email recipients of the original share
    created_at
    datetime
    Creation timestamp
    last_modified_at
    datetime
    Timestamp of the most recent modification
    referrer
    object
    Information about the advocate creating the conversion (Expand)
    Referrer
    customer
    object
    Present only if referral is a customer personal url or a share with a known customer (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    email
    string
    Present only if referral is an email personal url or a share with a known referring email
    name
    string
    Name of referrer, if conversion was from a share
    facebook_friends_count
    integer
    Number of Facebook friends of sharer, if known
    twitter_followers_count
    integer
    Number of Twitter followers of sharer, if known
    birthdate
    date
    Birthdate of sharer, if known

    Embedded JavaScript

    Friendbuy supports web application integration through JavaScript embedded on your website. This JavaScript enables functionality such as loading widgets, tracking customers, tracking products, tracking purchases, checking the status of a user visiting your site, and more.

    Required Code

    At a minimum, there are three JavaScript snippets that must be included on your site to enable Friendbuy’s referral functionality. These three snippets are Friendbuy’s JavaScript Library import code, Site Identification code, and Command Queue code.

    To grab these three snippets with your specific site id and include them on your website, please follow these steps.

    1. Log into to Friendbuy.
    2. Navigate to Settings > Integration Code.
    3. Add the code on every page of your website. For most web sites, this is accomplished by pasting the snippet once, immediately after your opening <head> tag, which should then make integration with Friendbuy available across all pages, secure and non-secure.

    Beyond the required code, the next three most important snippets to include on your website so that your referral program runs smoothly are Customer Tracking, Order Tracking and Widget Installation. You will find further integration instructions in each respective section below.

    Although not required, we strongly recommend that you include the Customer Tracking code snippet on all pages along with the above three mandatory snippets.

    Library

    (function (f, r, n, d, b, y) {
      b = f.createElement(r), y = f.getElementsByTagName(r)[0];b.async = 1;b.src = n;y.parentNode.insertBefore(b, y);
    })(document, 'script', '//djnf6e5yyirys.cloudfront.net/js/friendbuy.min.js');
    

    The library is the file with the implementation that executes the commands pushed into the Command Queue. This code is injected into the page asynchronously so that it doesn't block other page elements hosted on your website such as images, JavaScript, or CSS.

    Additionally, the library enables Friendbuy to cookie users for referral tracking and pooling for widget A/B testing.

    Command Queue

    Interaction with the library takes place through a JavaScript array assigned to the top-level namespace (i.e., window), which serves as a queue for your commands — an approach similar to that of Google Analytics. You can add commands to the array by calling the push() method with an “instruction” as its sole argument.

    window['friendbuy'] = window['friendbuy'] || [];
    window['friendbuy'].push([command, target, ...additional_arguments]);
    

    Five commands are supported:

    Command Purpose Description
    site Account Identification Identify your account with your site key.
    track Data Tracking Provide information about users, purchases, and products that will be available to widgets on the page, giving you control over what the widgets display or share.
    widget Widget Configuration Add a widget to a page and specify its placement and other settings.
    subscribe Event Handling Register callbacks for actions performed by a user on a widget, such as opening or closing a widget, or completing a share.
    invoke Command Invocation Invoke additional Friendbuy services.

    Site Identification, which includes the site key, must precede all other Friendbuy direction. The order in which you specify additional commands is somewhat flexible, though you do need to push subscribe commands after all widgets have been placed and configured.

    Each command that can be added to the array is described in the sections below.

    Site Identification

    window['friendbuy'].push(['site', 'site-d2a64238-www.example.com']);
    

    The ['site', siteKey] command is used to identify your account in our platform so we can properly attribute referral data. You can find your site key in the in Friendbuy web application at Settings > Integration Code.

    Tracking

    The track command is used to send customer, order, and product data to Friendbuy.

    Customer Tracking

    window['friendbuy'].push(['track', 'customer', {
      "id": "C-7896751",
      "email": "alexc@example.org",
      "first_name": "Alex",
      "last_name": "Chu",
      "stripe_customer_id": "cus_8QEiAlcRfEPMOh",
      "chargebee_customer_id": "djkl23jfdkslf"
    }]);
    

    You can pass Friendbuy unique information about a customer such as id, email address, and name. This information enables a more seamless integration with your referral program, allowing Friendbuy to auto-populate widget fields, as well as tie referral activity to specific customers as they are defined in your system.

    The ['track', 'customer', customerDetail] command instructs Friendbuy to track a customer in this session. The customer detail is an object with the following properties:

    Property Type Required Description
    id string Y Your identifier for associating a user with a share or a purchase
    email string N Email address of the customer. Widgets will automatically populate the from field when sharing through email when email is present. This value is stored for use in fraud checking. The stored value will be updated if a new email address is included for a known customer id
    first_name string N First name of the customer. This value will be stored and used in the future to facilitate personalization of widgets and communication. The stored value will be updated if a new value is included for a known customer id
    last_name string N Last name of the customer. This value will be stored and used in the future to facilitate personalization of widgets and communication. The stored value will be updated if a new value is included for a known customer id
    stripe_customer_id string N The id of the customer within Stripe, if known
    chargebee_customer_id string N The id of the customer within Chargebee, if known

    If providing a customer id, we will check if there is an existing customer record in Friendbuy. If so, the record will be updated with any new information specified in the request body. If no customer record exists, a new one will be created.

    Order Tracking

    window['friendbuy'].push(['track', 'order', {
      "id": "0382138317",
      "amount": "325.94",
      "coupon_code": "C3333",
      "new_customer": false,
      "email": "sam@example.org"
    }]);
    

    When notifying Friendbuy of an order, we will automatically use the cookie (if present) or coupon code (if provided in the order tracking call) to establish attribution back to a referral. If attribution is established, a conversion will be generated in Friendbuy’s system. The attribution ties both the advocate and friend to the order.

    To grab the order tracking snippet and it include it on your website, please follow these steps: 1. Log into to Friendbuy. 1. Navigate to Settings > Integration Code. 1. Add the code on your conversion event page (most commonly, the Order Confirmation page) by pasting the snippet in your document <head>, just under the Site Identification code.

    The ['track', 'order', orderDetail] command instructs Friendbuy to track an order in this session. The order detail parameter is an object with the following properties:

    Property Type Required Description
    id string Y Configure this property so that a unique value is provided to Friendbuy for every order. A common example of this is an Order Number or Transaction ID. If your conversion event is something other than a purchase (e.g., signups, registrations), you can pass a variable that provides us with a unique value for that event, such as a Sign Up ID.
    amount string N The amount in currency units of the order
    coupon_code string N A coupon code used with the order. This can allow us to track a purchase back to a referral if purchaser does not have our tracking cookie present
    new_customer boolean N Whether the order was made by a new customer (true) or an existing customer (false)
    email string N The email address of the person making the order. Used by Friendbuy for fraud detection

    Product Tracking

    window['friendbuy'].push(['track', 'products', [
      {
        "sku": "Z-4083",
        "price": "28.00",
        "quantity": "2"
      }
    ]]);
    

    In addition to notifying Friendbuy that an order has taken place, you can also let us know what products were included. The product properties can even be used to indicate other details about an order, for example, the product may be an introductory sign up.

    The ['track', 'products', listOfProducts] command instructs Friendbuy to track a list of products in this session. Each product in the listOfProducts array parameter is an object with the following properties:

    Property Type Required Description
    sku string Y An identifier for a purchased product
    price string N The price of the product
    quantity string N Number of units of the product that were purchased

    Widget Management

    Use the widget command to place widgets on your web page and control configuration, and include additional options. You may issue the widget command multiple times, once for each Friendbuy widget that you would like to add to your web page. The widget command has the following form:

    ['widget', widget_id, selector?, options?]

    where widget_id is the required id of the widget (found in the Widget Installation Code of the Friendbuy application), selector is an optional string identifying the HTML element where the widget is to be placed, and options is an optional object with configuration details.

    The three parameters are discussed in the following sections.

    Identification

    Example

    // Place the widget with id a0-Ybn into its default location
    // on the page: the HTML element with id "friendbuy-a0-Ybn"
    window['friendbuy'].push(['widget', 'aO-Ybn']);
    

    The widget_id parameter determines which widget to add to the page. The widget_id is the only required component of the widget command. You can find the widget ID in the Friendbuy platform by following steps:

    1. Login to Friendbuy.
    2. Navigate to Referral & Sharing > Widgets and select the desired widget from the list.
    3. Click on the Widget Installation Code tab.

    Selector

    Example

    // Explicit specification of widget placement. Place widget
    // with id a0-Ybn into HTML divs with the class "widget"
    window['friendbuy'].push(['widget', 'aO-Ybn', 'div.widget']);
    

    Use the optional selector argument to identify the HTML element in which the widget will appear. If this argument is not provided, a default selector, a class formed by prefixing friendbuy- to the widget id, will be used.

    Widget Options

    Example

    // Place widget a0-Ybn into its default selector with a wide
    // range of options
    window['friendbuy'].push(['widget', 'aO-Ybn', {
      configuration: {
        // Waits five seconds after loading to display
        auto_delay: 5000,
        // Does not require a button to show the widget
        share_button: false
      },
      criteria: {
        // Widget will appear only for VIP customers
        // and if loaded within a pre-configured time
        // period
        limitedTime: true,
        customerType: 'VIP'
      },
      content: {
        // Places values into a the widget template for
        // a personalized greeting
        firstname: "Jordan",
        city: "Cybertown"
      },
      parameters: {
        survey: '<?php echo $order->isSurvey() ?>'
      }
    }]);
    

    Example

    // URL generated when a referral link is clicked and the survey was completed
    'http://yoursite.com?survey=true'
    

    The options argument to the widget command can take many forms. Add as many or as few options as you would like during widget placement. Four options (configuration, criteria, content, and parameters) are supported and are described below.

    Configuration

    The display configuration options control how and when a widget is invoked.

    Criteria

    The criteria option is a collection of key-value pairs, used to conditionally display the widget. This allows you to target specific customers rather than all visitors to your site. For example, you may want to run a campaign just for existing customers, or a subset of existing customers.

    Content

    The content option is a collection of key-value pairs. These values are used to dynamically display text in a widget. An example use case is personalizing a widget to display the name of the logged in customer.

    To take advantage of this functionality, the template applied to your widget must be customized by Friendbuy. The code added to the template can be set up so that the content values are either required or optional. If optional, the content placeholder in the widget will be hidden if no value is passed.

    Parameters

    The parameters option is a collection of key-value pairs. These values are added to referral links for the associated widget to facilitate tracking and reporting on referral traffic.

    When you provide custom parameters with a widget, Friendbuy will include them in the referral URLs that are created from that widget. When someone clicks on a shared link, a query string parameter will be added for each of the custom parameters provided.

    Event Listeners

    You can subscribe to client-side widget events to ensure widgets are properly being served and tailor the website experience for users after they successfully share.

    The events you can subscribe to along with their accompanying event handlers are described below.

    Window Open Event

    Example Subscription Call

    window['friendbuy'].push(['subscribe', 'widget.open',
      function (widget) {
        // Handler code
      }
    ]);
    

    The ['subscribe', 'widget.open', callback] command registers a callback for the widget.open event, which fires when a Friendbuy widget has been opened by the user. When called, the subscribed event handler function is passed the opened widget as its sole argument.

    Window Close Event

    Example Subscription Call

    window['friendbuy'].push(['subscribe', 'widget.close',
      function (widget) {
        // Handler code
      }
    ]);
    

    The ['subscribe', 'widget.close', callback] command registers a callback for the widget.close event, which fires when a Friendbuy widget has been closed by the user. When called, the subscribed event handler function is passed the closed widget as its sole argument.

    Share Success Event

    Example Subscription Call

    window['friendbuy'].push(['subscribe', 'share.success',
      function (share) {
        // Handler code
      }
    ]);
    

    Example Callback Argument

    {
      "id": "2789",
      "network": "facebook",
      "message": "Such an amazing product"
    }
    

    The ['subscribe', 'share.success', callback] command registers a callback for the share.success event, which fires when a user successfully completes a share using a Friendbuy widget. Subscribing to this event allows you to trigger activity on your website based on shares by your customers. You can surface a “thank you” popup, send the visitor to a special page intended solely foryour advocates, or customize your page depending on the social network destination or the shared message.

    The object passed to the handler has the following properties:

    Property Type Description
    id string A unique identifier for the share
    network string The destination of the share (e.g., "facebook", "twitter", etc.)
    message string The message that accompanied the share

    Services

    Visitor Status Service

    Example Invocation

    window['friendbuy'].push(['invoke', 'visitor_status',
      function (response) {
        // Handler code
      }
    ]);
    

    Example Callback Object

    {
      "friendbuy_click": "share",
      "share": {
        "id": 196418,
        "referral_code": "uxC",
        "message": {
          "id": "100001965159666_428859647189537",
          "content": "This is my favorite tennis racket ever",
          "network": "facebook"
        },
        "campaign": {
          "id": 233,
          "name": "Fall Shoe Sale",
          "published": true,
          "referral_incentive": {
            "type": "fixed_cash",
            "value": 25
          },
          "created_at": "2015-08-09T03:20:11.098230-07:00"
        },
        "ip_address": "8.8.8.8",
        "newsletter_opt_in": true,
        "send_reminder": true,
        "created_at": "2017-01-13T19:18:38.239Z",
        "detail_uri": "https://developer-api.friendbuy.com/v2/shares/196418",
        "email_recipients": [
          "pele@example.br",
          "messi@example.ar"
        ],
        "sharer": {
          "name": "Taylor Gomez",
          "email": "tgo@example.net",
          "customer": {
            "account_id": "JAYZ",
            "id": "JAYZ",
            "email_address": "jzheng@example.mil",
            "first_name": "Jaylene",
            "last_name": "Zheng",
            "stripe_customer_id": "cus_Agg4bCEhno7A1E",
            "chargebee_customer_id": "4gkYnd21ouvW",
            "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
          },
          "facebook_friends_count": 987,
          "twitter_followers_count": 121393,
          "birthdate": "1989-11-09"
        }
      },
      "purl": {
        "campaign": {
          "id": 233,
          "name": "Fall Shoe Sale",
          "published": true,
          "referral_incentive": {
            "type": "fixed_cash",
            "value": 25
          },
          "created_at": "2015-08-09T03:20:11.098230-07:00",
          "archived": false,
          "objective": "referral",
          "distribution": 50,
          "is_champion": true,
          "campaign_group_id": "hm-NNz"
        },
        "customer": {
          "account_id": "JAYZ",
          "id": "JAYZ",
          "email_address": "jzheng@example.mil",
          "first_name": "Jaylene",
          "last_name": "Zheng",
          "stripe_customer_id": "cus_Agg4bCEhno7A1E",
          "chargebee_customer_id": "4gkYnd21ouvW",
          "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
        },
        "destination_url": "http://mycompany.example.com/rewards/908",
        "email": "jzheng@example.mil",
        "id": "100",
        "referral_code": "uxC"
      },
      "reminder_email": {
        "campaign": {
          "id": 233,
          "name": "Fall Shoe Sale",
          "published": true,
          "referral_incentive": {
            "type": "fixed_cash",
            "value": 25
          },
          "created_at": "2015-08-09T03:20:11.098230-07:00",
          "archived": false,
          "objective": "referral",
          "distribution": 50,
          "is_champion": true,
          "campaign_group_id": "hm-NNz"
        },
        "id": "100001965159666_428859647189537",
        "created_at": "2015-08-09T03:20:11.098230-07:00",
        "referral_code": "uxC",
        "sharer": {
          "customer": {
            "account_id": "JAYZ",
            "id": "JAYZ",
            "email_address": "jzheng@example.mil",
            "first_name": "Jaylene",
            "last_name": "Zheng",
            "stripe_customer_id": "cus_Agg4bCEhno7A1E",
            "chargebee_customer_id": "4gkYnd21ouvW",
            "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
          },
          "email": "jzheng@example.mil"
        },
        "share": {
          "id": 196418,
          "referral_code": "uxC",
          "message": {
            "id": "100001965159666_428859647189537",
            "content": "This is my favorite tennis racket ever",
            "network": "facebook"
          },
          "campaign": {
            "id": 233,
            "name": "Fall Shoe Sale",
            "published": true,
            "referral_incentive": {
              "type": "fixed_cash",
              "value": 25
            },
            "created_at": "2015-08-09T03:20:11.098230-07:00"
          },
          "ip_address": "8.8.8.8",
          "newsletter_opt_in": true,
          "send_reminder": true,
          "created_at": "2017-01-13T19:18:38.239Z",
          "detail_uri": "https://developer-api.friendbuy.com/v2/shares/196418",
          "email_recipients": [
            "pele@example.br",
            "messi@example.ar"
          ],
          "sharer": {
            "account_id": "JAYZ",
            "id": "JAYZ",
            "email_address": "jzheng@example.mil",
            "first_name": "Jaylene",
            "last_name": "Zheng",
            "stripe_customer_id": "cus_Agg4bCEhno7A1E",
            "chargebee_customer_id": "4gkYnd21ouvW",
            "detail_uri": "https://developer-api.friendbuy.com/v2/customers/1"
          }
        }
      },
      "self_referred": false,
      "timestamp": "2015-08-09T03:20:11.098230-07:00",
      "signature": "bGaQzRncJifoE9PgtGdz99l8ffY="
    }
    

    The ['invoke', 'visitor_status', callback] command allows Friendbuy to pass details about a user visiting your website to a callback function. This data includes whether the visitor has clicked on a Friendbuy referral link into the site within the last hour, and if so, the source of the click, and whether or not the click indicates a self-referral.

    Common use cases for visitor status include:

    Signature

    You can verify the authenticity of the Visitor Status from Friendbuy by analyzing its cryptographic signature. Friendbuy signs the response using the following technique:

    1. Sort the attributes of the status object, excluding signature, alphabetically, using Unix-style case-sensitive sort order.
    2. Concatenate the attribute names and values with no delimiters. If the value is itself an object, concatenate only its id. For example:

      { purl: { customer: "1234", id: "456" }, friendbuy_click: "purl", self_referred: "true" }

      becomes:

      friendbuy_clickpurlpurl456self_referredtrue

    3. The signature is placed in the X-FRIENDBUY-SIGNATURE header, and is computed by Base64-encoding the HMAC-SHA1 hash of the request body with your Friendbuy secret key.

    Response Model

    VisitorStatus
    friendbuy_clickOne of 'share', 'purl', 'reminder_email', or 'none'. If 'none', the current user has not clicked a Friendbuy link into your site in the past hour. If 'share', the share property will have information about the clicked share. If 'purl', the purl property will have information about the clicked personal URL. If 'reminder_email', the 'reminder_email' property will have information about the clicked reminder email
    shareInformation about the share, if friendbuy_click === 'share' (Expand)
    ShareExcerpt
    id
    integer
    Friendbuy internal id for this share
    referral_code
    string
    Short alphanumeric code
    message
    object
    Message sent along with share (Expand)
    ShareMessage
    id
    string
    Message id assigned by facebook or twitter
    content
    string
    Text entered by the advocate
    network
    string
    Distribution channel for this share
    campaign
    object
    Campaign that is being shared (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    ip_address
    string
    IP address of the share
    newsletter_opt_in
    boolean
    Whether a newsletter opt in should take place with the share
    send_reminder
    boolean
    Whether a reminder should be sent for the share
    created_at
    datetime
    Share creation timestamp
    detail_uri
    string
    URI endpoint at which to get full details of the share
    email_recipients
    array
    JSON-formatted array of recipients for the share, present only if (1) the share is an email share and (2) the merchant is permitted to access this information (*Contact Friendbuy to inquire about the ability to access the recipient list*)
    sharer
    object
    Information for the entity making the share (Expand)
    SharerExcerpt
    name
    string
    Name of sharer, if known
    email
    string
    Email address to receive the reward, if eventually eligible
    customer
    object
    Customer information, if available at the time of share (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    facebook_friends_count
    integer
    Number of Facebook friends, if known
    twitter_followers_count
    integer
    Number of Twitter followers, if known
    birthdate
    date
    Birthdate, if known
    purlInformation about the personal url, if friendbuy_click === 'purl' (Expand)
    PersonalUrlExcerpt
    campaignThe campaign to which the personal url is associated (Expand)
    Campaign
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    archived
    boolean
    Whether the campaign has been archived
    objective
    string
    One of referral, email_capture, or influencer
    distribution
    integer
    Percentage chance that the campaign’s widget will be served (100 for campaigns that have no variants)
    is_champion
    boolean
    Whether the campaign is designated as the champion of its group
    campaign_group_id
    string
    Identifier denoting the group (of campaign variants) to which the campaign belongs
    customerThe customer owning the personal url (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    destination_url
    string
    URI in the merchant’s site that the trackable link redirects to
    email
    string
    Email associated with the customer
    id
    string
    The internal id of the personal url
    referral_code
    string
    Short alphanumeric code (e.g., uxC)
    reminder_emailInformation about the reminder email, if friendbuy_click === 'reminder_email' (Expand)
    ReminderEmailExcerpt
    campaignThe campaign for which this reminder email is sent (Expand)
    Campaign
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    archived
    boolean
    Whether the campaign has been archived
    objective
    string
    One of referral, email_capture, or influencer
    distribution
    integer
    Percentage chance that the campaign’s widget will be served (100 for campaigns that have no variants)
    is_champion
    boolean
    Whether the campaign is designated as the champion of its group
    campaign_group_id
    string
    Identifier denoting the group (of campaign variants) to which the campaign belongs
    id
    string
    Message id assigned by facebook or twitter
    created_at
    datetime
    Creation timestamp
    referral_code
    string
    Short alphanumeric code (e.g., uxC)
    sharerThe sharer of the reminder email (Expand)
    ReminderEmailSharerExcerpt
    customerThe customer that shared (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    email
    string
    Email associated with the customer
    shareThe share to which this reminder applies (Expand)
    ReminderEmailShareExcerpt
    id
    integer
    Friendbuy internal id for this share
    referral_code
    string
    Short alphanumeric code
    message
    object
    Message sent along with share (Expand)
    ShareMessage
    id
    string
    Message id assigned by facebook or twitter
    content
    string
    Text entered by the advocate
    network
    string
    Distribution channel for this share
    campaign
    object
    Campaign that is being shared (Expand)
    CampaignExcerpt
    id
    integer
    Friendbuy-assigned id for the campaign
    name
    string
    Name of the campaign
    published
    boolean
    Whether the campaign has been published
    referral_incentive
    object
    Incentive for the campaign (Expand)
    ReferralIncentive
    type
    string
    One of percent_discount, fixed_cash, fixed_points, stripe_credit, chargebee_credit or other
    value
    number
    Amount of the reward in units of the reward type
    created_at
    datetime
    Creation timestamp
    ip_address
    string
    IP address of the share
    newsletter_opt_in
    boolean
    Whether a newsletter opt in should take place with the share
    send_reminder
    boolean
    Whether a reminder should be sent for the share
    created_at
    datetime
    Share creation timestamp
    detail_uri
    string
    URI endpoint at which to get full details of the share
    email_recipients
    array
    JSON-formatted array of recipients for the share, present only if (1) the share is an email share and (2) the merchant is permitted to access this information (*Contact Friendbuy to inquire about the ability to access the recipient list*)
    sharerThe customer that shared (Expand)
    CustomerExcerpt
    account_id
    string
    The id assigned by you to your customer (not the same as the internal Friendbuy-assigned id)
    id
    string
    Copy of the account_id field
    email_address
    string
    Email associated with the customer
    first_name
    string
    Customer first name
    last_name
    string
    Customer last name
    stripe_customer_id
    string
    Stripe’s id for the customer
    chargebee_customer_id
    string
    Chargebee’s id for the customer
    detail_uri
    string
    URI at which complete details of the customer can be retrieved
    self_referredIndicates whether the visitor is an advocate clicking on their own referral link. Note, this calculation is dependent on which fraud check settings have been enabled in the Friendbuy platform, specifically the Browser and/or IP Address checks.
    timestampWhen this response was formed
    signatureFriendbuy’s signature for this message, computed as described above