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    

Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

/address-book

Your app may already let your users import their address book contents to support an invite flow. Typical sources of address books include:

After importing from these sources, you are faced with the task of picking which entries to recommend to your users. In reality, those address books can be a pretty big mess. Some addresses are clearly irrelevant: some spammer, a newsletter, a local pizza delivery service. Then there are duplicate names, contacts without email addresses, etc.

YesGraph can help you clean up your user's address books and make the best recommendations.

The Address Book service allows you to POST the address book contents you receive from your user's address book. This request will return an ordered list of cleaned up, filtered and deduplicated entries. If the backfill flag is ON, it does not return ranked results in the response.

UPDATE 11/4/2015: This endpoint now includes an optional "limit" parameter, and also returns the ranked list directly. So the process of retrieving a ranked address book can be done with one call. The GET method is still available for retrieving address books previously stored in the system.

UPDATE 11/17/2015:

  • The POST request now returns ranked contacts on both POST and GET requests, so you can get a ranked contact list without calling a GET after POST.
  • The endpoint includes an optional "filter_suggested_seen" parameter for the GET or POST requests, which ranks contacts that have not been suggested above contacts that have been suggested before.

UPDATE 01/30/2017:

  • The endpoint includes an optional "backfill" flag for the requests. It is meant to be used for backfilling many users' address books into the YesGraph API in a more efficient manner from your server. It does not return ranked results in the response.

POST /address-book

Should be called when you gain access to the user's address book.

You can upload multiple address books (from each source) and they will be returned with duplicates removed. This allows you to send partial updates. If you need to remove an address book see the listing and deletion endpoints.

# Use YesGraph's Python SDK 
# https://github.com/yesgraph/python-yesgraph
from yesgraph import YesGraphAPI
api = YesGraphAPI("YOUR_SECRET_KEY")
entries = [
    {
      "name": "Ivan Kirigin",
      "emails": ["ivan@yesgraph.com"],
      "phones": ["+1 555 123 4567"],
      "photos": ["http://j.mp/ivan_jpg"],
      "data": {"picture_url": "http://j.mp/ivan_jpg"}
    },
    {
        'name': 'Jonathan Chu',
        'nickname': 'Jon',
        'company': 'YesGraph',
        'title': 'Software Engineer',
        'last_message_sent_date': "2015-03-28T20:16:12+00:00",
        'last_message_received_date': "2015-03-28T20:16:12+00:00",
        'times_contacted': 100,
        'is_favorite': 1,
        'pinned': 10,
        'websites': [{'url': 'http://jonathanchu.com/', 'type': 'home'}],
        'addresses': [{'po_box': '12345', 'street': '708 Winslow', 'city': 'Redwood City', 'state': 'CA',
                       'postal_code': '11111', 'country': 'USA', 'type': 'work'}],
        'ims': [{'name': 'jonchu', 'type': 'aol'}],
        'emails': ['jonathan.chu@me.com'],
    },
    {
      "name": "Vincent Driessen",
      "emails": ["me@nvie.com", "vincent@yesgraph.com"]
    },
    {
     'name': 'Abigail Kirigin',
     'emails': ['abigail.kirigin@gmail.com'],
     'phones': ['+1 617-724-4117', '+1 617-724-4890'],
     },
    {
      "emails": ["hous-123456@craigslist.org"]
    },
    {
      "name": "George Hickman",
      "emails": ["george@yesgraph.com"],
      "data": {"foo": "bar"}
    }
]

api.post_address_book(user_id="1234", entries=entries, source_type="gmail", source_name="Vincent Driessen", source_email="vincent@yesgraph.com", filter_suggested_seen=0)

### Response

{
  "batch_id": "1343cd9e-3646-4fcb-ae9c-b2933927dfcf",
  "data": [
    {
      "data": {},
      "email": "jonathan.chu@me.com",
      "emails": [
        "jonathan.chu@me.com"
      ],
      "name": "Jonathan Chu",
      "phone": null,
      "phones": [],
      "rank": 1,
      "score": 0.5664803466814523
    },
    {
      "data": {},
      "email": "vincent@yesgraph.com",
      "emails": [
        "vincent@yesgraph.com",
        "me@nvie.com"
      ],
      "name": "Vincent Driessen",
      "phone": null,
      "phones": [],
      "rank": 2,
      "score": 0.34132458015246514
    },
    {
      "data": {
        "picture_url": "http://j.mp/ivan_jpg"
      },
      "email": "ivan@yesgraph.com",
      "emails": [
        "ivan@yesgraph.com"
      ],
      "name": "Ivan Kirigin",
      "phone": "+1 555 123 4567",
      "phones": [
        "+1 555 123 4567"
      ],
      "rank": 3,
      "score": 0.2287466968879715
    },
    {
      "data": {},
      "email": "abigail.kirigin@gmail.com",
      "emails": [
        "abigail.kirigin@gmail.com"
      ],
      "name": "Abigail Kirigin",
      "phone": "+1 617-724-4890",
      "phones": [
        "+1 617-724-4117",
        "+1 617-724-4890"
      ],
      "rank": 4,
      "score": -0.05331033026021581
    }
  ],
  "message": "Address book for 35633 added.",
  "meta": {
    "app_name": "Penderry",
    "time": 5.001199960708618,
    "total_count": 4,
    "user_id": "35633"
  }
}
curl -X POST \
    -H 'Authorization: Bearer YOUR_SECRET_KEY' \
    -H 'Content-Type: application/json' \
    -d '
{
  "user_id": "1234",
  "source": {
    "name": "Vincent Driessen",
    "email": "vincent@yesgraph.com",
    "type": "gmail"
  },
  "entries": [
    {
      "name": "Ivan Kirigin",
      "emails": ["ivan@yesgraph.com"],
      "phones": ["+1 555 123 4567"],
      "data": {"picture_url": "http://j.mp/ivan_jpg"},
      "photos": ["http://j.mp/ivan_jpg"]
    },
    {
      "name": "Jonathan Chu",
      "nickname": "Jon",
      "company": "YesGraph",
      "title": "Software Engineer",
      "last_message_sent_date": "2015-03-28T20:16:12+00:00",
      "last_message_received_date": "2015-03-28T20:16:12+00:00",
      "times_contacted": 100,
      "is_favorite": 1,
      "pinned": 10,
      "websites": [{"url": "http://jonathanchu.com/", "type": "home"}],
      "addresses": [{"po_box": "12345", "street": "708 Winslow", "city": "Redwood City", "state": "CA",
                       "postal_code": "11111", "country": "USA", "type": "work"}],
      "ims": [{"name": "jonchu", "type": "aol"}],
      "emails": ["jonathan.chu@me.com"]
    },
    {
      "name": "Vincent Driessen",
      "emails": ["me@nvie.com", "vincent@yesgraph.com"]
    },
    {
      "emails": ["post@posterous.com"]
    },
    {
      "emails": ["hous-123456@craigslist.org"]
    },
    {
      "name": "George Hickman",
      "emails": ["george@yesgraph.com"],
      "data": {"foo": "bar"}
    }
  ]
}
		' \
    https://api.yesgraph.com/v0/address-book

### Response

{
  "batch_id": "39d06778-261a-4d97-b031-ea62c761da99",
  "data": [
    {
      "data": {
        "picture_url": "http://j.mp/ivan_jpg"
      },
      "email": "ivan@yesgraph.com",
      "emails": [
        "ivan@yesgraph.com"
      ],
      "name": "Ivan Kirigin",
      "phone": "+1 555 123 4567",
      "phones": [
        "+1 555 123 4567"
      ],
      "rank": 1,
      "score": 241.0
    },
    {
      "data": {},
      "email": "vincent@yesgraph.com",
      "emails": [
        "vincent@yesgraph.com",
        "me@nvie.com"
      ],
      "name": "Vincent Driessen",
      "phone": null,
      "phones": [],
      "rank": 2,
      "score": 198.5
    },
    {
      "data": {},
      "email": "jonathan.chu@me.com",
      "emails": [
        "jonathan.chu@me.com"
      ],
      "name": "Jonathan Chu",
      "phone": null,
      "phones": [],
      "rank": 3,
      "score": 8.5
    }
  ],
  "message": "Address book for 1234 added.",
  "meta": {
    "app_name": "testkendall",
    "time": 0.07370972633361816,
    "total_count": 3,
    "user_id": "1234"
  }
}

Arguments for POST

user_id

required

int or string

The user ID to for the address-book you want to POST. This should be the internal user ID you use to refer to this user. It can be a numeric user ID or a string.
Note: if you pass in a numeric user ID, it will be converted to a string, and thus returned as a string.

source

required

object

Email address, name, phone number, and source type of the user account connecting the address book (the source). For the web, you should send the email address of the GMail account connecting. For mobile, this typically is the email address of the device owner, or the email address you stored for this user's account.

entries

required

list of entries

Address book contents.

filter_suggested_seen

optional

int (0 or 1)

This option allows seen suggested contacts to be ranked lower than contacts that have not been suggested yet, so fresh entries can be shown to the user.

filter_existing_users

optional

int (0 or 1)

This option will filter out existing users (posted to the /users endpoint) so they will not be returned in the ranked addressbook

filter_invites_sent

optional

int (0 or 1)

This option will filter out rows that have previously been sent invites by this user.

promote_existing_users

optional

int (0 or 1)

This option will promote existing users to the top of the address book rankings.

promote_matching_domain

optional

int (0 or 1) or string (email domain)

This option will promote users with a particular email domain to the top of the address book rankings. If the value is a domain, it will target that domain. If the value is 1, it will target the address book owner's email domain.

filter_blank_names

optional

int (0 or 1)

This option will filter out rows with blank names.

limit

optional

int

This is an optional limit for the top number of ranked rows to be returned

backfill

optional

int (0 or 1)

This flag should be used for backfilling address-books, without returning the ranked results in the response.

Source objects

name

optional

string

The recorded name of the address book account (the owner).

email

optional

string

Email address of the address book account (the owning email account).

phone

optional

string

Phone number of the address book account (the owning email account), if known. We strongly recommend storing phone numbers in E.164 format, e.g. +1 555 123 4567.

type

optional

string

Describes where this address book came from. Valid entries are: 'ios', 'gmail', and 'android'.

Entries objects

name

optional

string

The recorded name in the address book (e.g. coming from GMail)

email

optional

string

Single email address of the address book entry. It is preferred you use the emails (plural) key.
Example: "john.doe@gmail.com"

emails

optional

list

All email addresses known for this address book entry.
Example:["john.doe@acme.com", "john.doe@gmail.com"]

phone

optional

string

Single phone number of the address book entry, if available. It is preferred you use the phones (plural) key instead.
We strongly recommend storing phone numbers in E.164 format.
Example: "+1 555 123 4567"

phones

optional

list

All phone numbers known for this address book entry.
We strongly recommend storing phone numbers in E.164 format.
Example: ["+1 555 123 4567", "+1 555 123 6543"]

photos

optional

list

All profile photos known for this entry in the form of URLs.

data

optional

object

Free-form JSON object to attach extra attributes to an entry that have meaning to your app. This could be useful for storing image URLs, or an internal reference ID. We'll return this data untouched in GET /address-book.

nickname

optional

string

This is the contact nickname or alias

title

optional

string

Title for the contact

company

optional

string

Company or organization for the contact

is_favorite

optional

string

If the user has "favorited" his contact on platforms like Android where this is supported

pinned

optional

integer

If the user has "pinned" the contact in a position on a platform such as Android

times_contacted

optional

integer

The number of times the user has messaged this contact

last_message_sent_date

optional

date

The date and time the user last sent this contact a message. This is an ISO 8601 date string or a Unix timestamp (integer). See the Dates section for details.

last_message_received_date

optional

date

The date and time the user last received a message from contact. This is an ISO 8601 date string or a Unix timestamp (integer). See the Dates section for details.

addresses

optional

list

List of addresses for this contact, as described in below table

websites

optional

list

List of websites for this contact, as described in table below

ims

optional

list

List of instant messenger names for this contact, as described below

entries: addresses

Addresses are optional but give us more data about the user which we can use to improve our rankings algorithm. Each object in the list is a dictionary with the following items.

po_box

optional

string

This is the Post Office box for the user

street

optional

string

Street name

city

optional

string

state

optional

string

postal_code

optional

string

country

optional

string

type

optional

string

"home" or "work" or other type for this address object

entries: websites

List of the users websites. This is optional, however if the list includes items it must include the following.

url

required

string

This is the URL for the website

type

required

string

The type of website (e.g. "home" or "blog")

ims object in entries

Instant Messenger information. This list is optional, however if you include it the below fields are required.

name

required

string

The user's instant messenger screenname

protocol

required

string

The protocol, such as "jabber"

type

required

string

"work" or "home"

GET /address-book/:user_id

This example request retrieves the address book for user 1234.

# Use YesGraph's Python SDK 
# https://github.com/yesgraph/python-yesgraph
from yesgraph import YesGraphAPI
api = YesGraphAPI("YOUR_SECRET_KEY")
api.get_address_book("1234", filter_suggested_seen=0, limit=20)

### Response
{
  "meta": {
    "app_name": "test",
    "docs": "https://www.yesgraph.com/docs/#get-address-bookuser_id",
    "help": "Please contact support@yesgraph.com for any issues.",
    "time": 0.033014535903930664,
    "total_count": 10,
    "user_id": "1234",
  },
  "data": [
    {
      "phones": [],
      "emails": [
        "ivan@yesgraph.com"
      ],
      "email": "ivan@yesgraph.com",
      "name": "Ivan Kirigin",
      "phone": null,
      "data": {
        "picture_url": "http://j.mp/ivan_jpg",
        "ref": 123
      }
    },
    {
      "phones": [],
      "emails": [
        "george@yesgraph.com"
      ],
      "email": "george@yesgraph.com",
      "name": "George Hickman",
      "phone": null,
      "data": {
        "foo": "bar"
      }
    },
    {
      "phones": [],
      "emails": [
        "jonathan.chu@me.com"
      ],
      "email": "jonathan.chu@me.com",
      "name": "Jonathan Chu",
      "phone": null,
      "data": {}
    },
    {
      "phones": [],
      "emails": [
        "me@nvie.com"
      ],
      "email": "me@nvie.com",
      "name": null,
      "phone": null,
      "data": {}
    },
    {
      "phones": [],
      "emails": [
        "h.schroeder@gmail.com"
      ],
      "email": "h.schroeder@gmail.com",
      "name": "Heinz Schroeder",
      "phone": null,
      "data": {}
    }
  ]
}
curl \
    -H 'Authorization: Bearer YOUR_SECRET_KEY' \
    https://api.yesgraph.com/v0/address-book/1234
    
### Response

{
  "meta": {
    "app_name": "test",
    "docs": "https://www.yesgraph.com/docs/#get-address-bookuser_id",
    "help": "Please contact support@yesgraph.com for any issues.",
    "time": 0.033014535903930664,
    "total_count": 10,
    "user_id": "1234",
  },
  "data": [
    {
      "phones": [],
      "emails": [
        "ivan@yesgraph.com"
      ],
      "email": "ivan@yesgraph.com",
      "name": "Ivan Kirigin",
      "phone": null,
      "data": {
        "picture_url": "http://j.mp/ivan_jpg",
        "ref": 123
      }
    },
    {
      "phones": [],
      "emails": [
        "george@yesgraph.com"
      ],
      "email": "george@yesgraph.com",
      "name": "George Hickman",
      "phone": null,
      "data": {
        "foo": "bar"
      }
    },
    {
      "phones": [],
      "emails": [
        "jonathan.chu@me.com"
      ],
      "email": "jonathan.chu@me.com",
      "name": "Jonathan Chu",
      "phone": null,
      "data": {}
    },
    {
      "phones": [],
      "emails": [
        "me@nvie.com"
      ],
      "email": "me@nvie.com",
      "name": null,
      "phone": null,
      "data": {}
    },
    {
      "phones": [],
      "emails": [
        "h.schroeder@gmail.com"
      ],
      "email": "h.schroeder@gmail.com",
      "name": "Heinz Schroeder",
      "phone": null,
      "data": {}
    }
  ]
}

Arguments for GET

user_id

required

int

The user id associated with the addressbook you want to GET.

limit

optional

int

A limit on the number of objects to be returned. Defaults to all results.

filter_suggested_seen

optional

int(0 or 1)

This option allows seen suggested contacts to be filtered out of the addressbook, so fresh entries can be shown to the user.

filter_existing_users

optional

int (0 or 1)

This option will filter out existing users (posted to the /users endpoint) so they will not be returned in the ranked addressbook

filter_invites_sent

optional

int (0 or 1)

This option will filter out rows that have previously been sent invites by this user.

promote_existing_users

optional

int (0 or 1)

This option will promote existing users to the top of the address book rankings.

promote_matching_domain

optional

int (0 or 1)
or string (email domain)

This option will promote users with a particular email domain to the top of the address book rankings. If the value is a domain, it will target that domain. If the value is 1, it will target the address book owner's email domain.

filter_blank_names

optional

int (0 or 1)

This option will filter out rows with blank names.

DELETE /address-book/:user_id

Should be called if you wish to delete an addressbook for a particular user.

# Use YesGraph's Python SDK 
# https://github.com/yesgraph/python-yesgraph
from yesgraph import YesGraphAPI
api = YesGraphAPI("YOUR_SECRET_KEY")
api.delete_address_book("1234")

### Response
{'meta': {'time': 0.005160093307495117}, 'message': 'Address book for 1234 deleted.'}
curl -X DELETE \
    -H 'Authorization: Bearer YOUR_SECRET_KEY' \
    https://api.yesgraph.com/v0/address-book/1234
###

{
  "message": "Address book for 1234 deleted."
}

Arguments for DELETE

user_id

required

int

The user id associated with the addressbook you want to DELETE.

/address-book