Overview
The article provides a detailed guide on using the Referrals API to create and manage referral programs outside of Influitive. It covers the process of creating referrals through e-commerce systems, advancing referral statuses, and retrieving referral lists and specific referral details. The article also emphasizes the importance of setup instructions for API access and the use of tools like Zapier and Postman for API call facilitation.
Information
You can use the Referrals API to create referrals and award points for a referral, even if the event occurs somewhere outside of Influitive. For instance, for a purchase made on your e-commerce website, a sign-up action on your site, or even an offline transaction!
Using our API
We have a JSON REST API that can be used to fetch, create and advance referrals. Our full API documentation for referrals can be found here .
To set up your account for access to the Influitive API, consult this document . It will also show you how to get your X_ORG_ID and Authorization Token to use on API calls.
You can use services like Zapier or Postman to create API calls, or work with a developer as well.
A sample call to create a Referral might look like this:
POST /referrals HTTP/1.1
Host: api.influitive.com
Content-Type: application/json
Accept: application/json
Authorization: Token 6bfa3b6256add25b71159d56ffa9ad4e629f7a30
X_ORG_ID: 9774649d-5e6c-49f0-b559-694b3f9c76e3
{"referral":
{"prospect":{
"first_name":"Some",
"last_name":"Prospect",
"email":"some@prospect.com",
"title":"CMO"
},
"contact":{
"first_name":"Johnny",
"last_name":"Advocate",
"email":"johnny@advocate.com"
},
"campaign_id":"98160557-5a70-4306-949e-ee8d2ea7f4b4"}
}<br>
Create a Referral
This allows you to create a referral in the system, at whatever milestone you would like.
Create Referral API Specification
Input: The name/email of the referral, and the name/e-mail of the person being referred
Output: A confirmation of the referral, including the referral ID
Creating a Referral via an E-Commerce System
Sometimes you may want to create a referral in Influitive every time a purchase is made on an e-commerce site. Influitive will add unique parameters to the landing page you specified in your referral campaign called a share_toke n and campaign_id . These can be used to make an API call back to AdvocateHub to close the loop on the referral process.
For more details on creating a referral via an E-Commerce System look at our full article on this topic:
Referrals 2.0: Using E-commerce/B2C Referrals
A sample call to create a Referral via a share token might look like this:
POST /referrals HTTP/1.1
Host: api.influitive.com
Content-Type: application/json
Accept: application/json
Authorization: Token 6bfa3b6256add25b71159d56ffa9ad4e629f7a30
X_ORG_ID: 9774649d-5e6c-49f0-b559-694b3f9c76e3
{
"referral":
{
"prospect":
{
"first_name":"Tom",
"last_name":"Jones",
"email":"some@prospect.com"
},
"contact":
{
"share_token": "hhh4ca59-50f8-42dd-91d9-eff7fa4565b0"
},
"campaign_id":"98160557-5a70-4306-949e-ee8d2ea7f4b4",
"status": "won"
}
}
Advance a referral
This allows you to advance an existing referral in the system, to a further milestone.
Advance a Referral API Specification
Returning a list of Referrals
This allows you to return a list of all referrals across all campaign in the system, including the person who referred them and the milestone reach.
List Referrals API Specification
Returning a specific Referral
Given as input a specific referral ID, return the current milestone, the information on who the referral was and who referred them.
FAQ
How do I create a referral using the Referrals API?
To create a referral, you need the name and email of the referrer and the referred individual. The API will return a unique referral ID upon successful creation. Detailed instructions are available in the Create Referral API Specification.
Can the Referrals API integrate with e-commerce systems for referral creation?
Yes, the Referrals API can be used to create a referral each time a purchase is made on an e-commerce site. You'll need to use the unique parameters provided by Influitive, such as share_token and campaign_id, to make an API call to AdvocateHub.
What is the process for advancing a referral to a subsequent milestone?
Advancing a referral involves using the API to update the status of an existing referral to the next milestone. Detailed steps and API specifications can be found in the Advance a Referral API Specification.
How can I retrieve a list of all referrals or details of a specific referral?
To retrieve a list of all referrals, use the List Referrals API Specification. For details on a specific referral, including the current milestone, use the referral ID with the Show one Referral API Specification.
What tools can assist in creating API calls for the Referrals API?
Tools such as Zapier and Postman can help facilitate the creation of API calls. Additionally, you may work with a developer for more complex integrations or custom solutions.