The YesGraph Developer Hub

Welcome to the YesGraph developer hub. You'll find comprehensive guides and documentation to help you start working with YesGraph as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

JavaScript SDK

A JavaScript wrapper for the YesGraph API

YesGraph uses machine learning and social graph analysis to improve your app's viral growth. Given an address book, we rank your users' contacts so they send more invites and you win!

Want a drop-in invite flow?

The YesGraph SuperWidget is an easy to integrate, drop-in invite flow--with just one line of code! Get yours at www.yesgraph.com, or check out the docs over here.

Getting Started

  1. Create an app on www.yesgraph.com
  2. Find your app id on the Web Integration page in the code snippet.
  3. Include the YesGraph Javascript SDK on your site -- make sure to specify the data-app and id attributes!
<script id="yesgraph" data-app="YOUR_APP_ID" src="//cdn.yesgraph.com/yesgraph.min.js"></script>

If you already have some information about the current user, you can include that as well using data- attributes. We'll incorporate that information into our ranking, so that you get the best results possible!

Valid attributes include data-name, data-email, data-phone, data-location, and others. Check out the /users endpoint docs for more on this.

<script id="yesgraph"
				data-app="YOUR_APP_ID"
        src="//cdn.yesgraph.com/yesgraph.min.js"
        data-name="Augusta Lovelace"
        data-email="ada@gmail.com">
</script>

Response Handlers

All of the API methods fetch data asynchronously, so you'll want to tell each method what to do once the data is available. There are two ways to do this:

  1. You can optionally pass a "responseHandler" argument to any of the API methods. This is just a function to be called on the data once we get a successful API response. For example:
function myResponseHandler (data) {
	console.log(data);
}

YesGraphAPI.test(myResponseHandler);
  1. Alternately, each of the API methods returns a jQuery Promise object, so you can also use any of the built-in methods for those: then, done, fail, always, pipe, progress, state, and promise.
YesGraphAPI.test()
           .done(handleSuccess)
           .fail(handleError)
           .pipe(doSomething)
           .then(doSomethingElse);
  1. Lastly, these two strategies can work together:
YesGraphAPI.test(handleSuccess)
           .fail(handleError)
           .always(doSomething);

test

The test method is a convenience method, to help you confirm that you are properly set up and can access our API. You can optionally pass a responseHandler argument. [docs]

YesGraphAPI.test();

The response from this method should look something like this:

{
  "message": "You have successfully made an authorized request to the YesGraph API!",
  "meta": {
    "app_name": YOUR_APP_ID,
    "time": 0.00014162063598632812,
    "user_id": "YG-123456789-a1b2-1234-5678-a1b2c3456789"
  }
}

rankContacts

Use the rankContacts method to submit a raw address book [docs]. Pass in a Javascript object representing an address book. You can optionally pass a responseHandler argument.

The addressBook object should contain a "source" object and a list of "entries" objects. You can input way more data than in this example, so definitely check out the docs, but this is enough to get you started:

var addressBook = {
    "source": {
        "name": "Augusta Lovelace",
        "email": "ada@gmail.com",
        "type": "gmail"
    },
    "entries": [
        {
            "name": "Joe Schmoe",
            "emails": ["joe@yesgraph.com", "joseph@schmoseph.com"],
            "company": "YesGraph",
            "title": "Software Engineer"
        },
        {
            "emails": ["support@apple.com"],
            "phones": ["+1 800 MY APPLE"],
            "data": {"foo": "bar"}
        },
        {
            "name": "Dad",
            "emails": ["george.byron@hotmail.com"],
            "data": {"picture_url": "http://tinyurl.com/zctkrsf"}
        }
    ]
};

YesGraphAPI.rankContacts(addressBook);

A Note on Performance:

Use the rankContacts method when you first want to submit an address book for ranking, and as a convenience, the response data will contain the ranked results.

However, if you'd like to retrieve those results again later on, using getRankedContacts is the fastest way. It will return cached results, which is faster than ranking the results again each time.

getRankedContacts

Retrieve a previously ranked address book using the getRankedContacts method [docs]. You can optionally pass a responseHandler argument.

YesGraphAPI.getRankedContacts();

The response should look something like this:

{
  "meta": {
    "app_name": YOUR_APP_ID,
    "time": 0.00553584098815918,
    "total_count": 2,
    "user_id": "YG-123456789-a1b2-1234-5678-a1b2c3456789"
  },
  "data": [
    {
        "rank": 1,
        "score": 1.9576705489335122,
        "name": "Dad",
        "emails": ["george.byron@hotmail.com"],
        "data": {"picture_url": "http://tinyurl.com/zctkrsf"}
    },
    {
        "rank": 2,
        "score": 1.7161657326250732,
        "name": "Joe Schmoe",
        "emails": ["joe@yesgraph.com", "joseph@schmoseph.com"],
        "company": "YesGraph",
        "position": "Software Engineer"
    }
  ]
}

postSuggestedSeen

More Data == Faster Growth!

Once you've suggested some contacts for your user to invite, there are a few things you'll want to tell us:

  • which contacts the user saw,
  • which contacts they invited, and
  • which invites were accepted.

By tracking this data, we can progressively improve the ranking model for your app over time, and you'll grow faster!

Use the postSuggestedSeen method to let us know which contacts you suggested to the user [docs]. Pass in an object representing the contacts you suggested to the user and, optionally, a responseHandler.

var seenContacts = {
    "entries": [
        {
            "name":"Joe Schmoe",
            "emails": ["joe@yesgraph.com", "joseph@schmoseph.com"],
            "seen_at": "2015-12-31T23:59:59+00:00"
        },
        {
            "name": "Dad",
            "emails": ["george.byron@hotmail.com"]
            "data": {"picture_url": "http://tinyurl.com/zctkrsf"}
        }
    ]
};

YesGraphAPI.postSuggestedSeen(seenContacts);

postInvitesSent

More Data == Faster Growth!

Once you've suggested some contacts for your user to invite, there are a few things you'll want to tell us:

  • which contacts the user saw,
  • which contacts they invited, and
  • which invites were accepted.

By tracking this data, we can progressively improve the ranking model for your app over time, and you'll grow faster!

Use the postInvitesSent method to tell us who the user ended up inviting [docs]. We'll track which contacts users invited to your app, and we'll suggest more contacts like them! Pass in an object representing the invites that were sent and, optionally, a responseHandler.

var invitesSent = {
    "entries": [
        {
            "invitee_name":"Dad",
            "email": "george.byron@hotmail.com",
            "sent_at": "2016-01-01T01:01:01+00:00"
        },
        {
            "email": "ralph@lovelace.gov",
            "sent_at": "2016-01-01T01:01:02+00:00"
        }
    ]
};

YesGraphAPI.postInvitesSent(invitesSent);

postInvitesAccepted

More Data == Faster Growth!

Once you've suggested some contacts for your user to invite, there are a few things you'll want to tell us:

  • which contacts the user saw,
  • which contacts they invited, and
  • which invites were accepted.

By tracking this data, we can progressively improve the ranking model for your app over time, and you'll grow faster!

Use the postInvitesAccepted method to tell us which invites got accepted [docs]. We'll track which contacts are most likely to accept an invite to your app, and we'll suggest more contacts like them! Pass in an object representing the accepted invites.
Optionally, you can also pass in a responseHandler.

var invitesAccepted = {
    "entries": [{
        "new_user_id":"12345",
        "name": "George Byron",
        "email": "george.byron@hotmail.com",
        "accepted_at": "2016-01-02T12:00:00+00:00"
    }]
};

YesGraphAPI.postInvitesAccepted(invitesAccepted);

JavaScript SDK

A JavaScript wrapper for the YesGraph API