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 Information about the owner of the address book, as defined in the table below.
entries required list of entries A list of contacts in the address book, as defined in the table below.
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 address book.
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 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 (e.g., 'ios', 'gmail', or 'android').

Entry objects

name optional string The recorded name of the contact entry.
emails optional list All known email addresses for this contact entry.
email optional string A single email address for this contact entry. The emails (plural) key is preferred over this one.
phones optional list All known phone numbers for this contact entry.
phone optional string A single phone number for this contact entry. The phones (plural) key is preferred over this one.
photos optional list All known profile photo URLs for this contact entry.
data optional object Free-form JSON object to attach extra attributes of this contact entry that have meaning to your app. This could be useful for storing an internal reference ID, or social media handles, etc. We’ll return this data untouched in GET /address-book.
nickname optional string A nickname or alias for this contact.
title optional string A title for this contact.
company optional string A company or organization associated with this contact.
is_favorite optional int (0 or 1) If the user has “favorited” this contact on platforms like Android where this is supported.
pinned optional int (0 or 1) If the user has “pinned” this contact on platforms like Android where this is supported.
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 received a message from this 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 the table below.
websites optional list List of websites for this contact, as described in the table below.
ims optional list List of instant messenger names for this contact, as described in the table below.

Address objects

po_box optional string The Post Office box for this contact entry.
street optional string The street name for this contact entry.
city optional string The city name for this contact entry.
state optional string The state for this contact entry.
postal_code optional string The postal code for this contact entry.
country optional string The country for this contact entry.
type optional string The type of this address (e.g., “home” or “work”).

Website objects

url required string The URL for this contact’s website.
type required string The type of website (e.g., “home” or “blog”).

IMs objects

name required string The instant messenger screenname for this contact.
protocol required string The protocol for this screenname (e.g., “jabber”).
type required string The type of screenname (e.g., “home” or “work”)

GET /address-book/:user_id

This example request retrieves a saved address book for the specified user.

# 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 string The user id associated with the address book you want to GET.
limit optional integer A limit on the number of contacts to be returned. Defaults to all results.
filter_suggested_seen optional int (0 or 1) This option indicates that contacts previously suggested to this user shoud be filtered out of the address book, so that fresh suggestions can be shown instead.
filter_existing_users optional int (0 or 1) This option indicates that existing users of your app shoud be filtered out of the address book.
filter_invites_sent optional int (0 or 1) This option indicates that contacts previously invited by this user should be filtered out of the address book.
promote_existing_users optional int (0 or 1) This option indicates that existing users of your app should be promoted to the top of the ranked address book.
promote_matching_domain optional int (0 or 1) This option indicates that contacts with a particular email domain should be promoted to the top of the address book rankings. If the value is an email 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 indicates that contacts with an empty name field should be filtered out of the address book.

DELETE /address-book/:user_id

This example request deletes the saved address book for the specified 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 integer The user id associated with the address book you want to DELETE.