Overview Access Person API Graph API Usage Agreement

Person API

This resource is used to retrieve information about a person, identified by email address, email hash, or website profile ID.
Note: While undocumented here, the old v2 style queries will continue to work.
1. Requests
1.1. Email Address
1.2. Email Hash
1.3. Website Profile ID
2. Responses
2.1. HTTP Status Codes
2.2. Schema Definitions
2.3. Example Response
3. Client Libraries
4. Help

Requests

The API can be queried with HTTP GET requests. Your API key must be specified in the "Authorization" header. 
GET http://api.rapleaf.com/v3/person/email/dummy@rapleaf.com HTTP/1.1
Authorization: 25234823472

For testing (or if circumstances require it) you can send your API key as the "api_key" GET parameter instead. 
GET http://api.rapleaf.com/v3/person/email/dummy@rapleaf.com?api_key=25234823472 HTTP/1.1

The following sections describe which URLs to use when querying by email, email hash, and website profile ID, respectively.
Query by Email
http://api.rapleaf.com/v3/person/email/<email address>
  • email address is the address you wish to search.
  • The email address must be URL-encoded. For instance, "dum+my@rapleaf.com" would be encoded as "dum%2Bmy%40rapleaf.com"
Query by Email Hash
http://api.rapleaf.com/v3/person/hash/<algorithm>/<hashed email>
  • algorithm is the hash algorithm used. Valid algorithms are:
    • sha1
    • md5
  • hashed email is the hashed version of the email address, as a hex encoded string.
  • Email addresses must be lowercased and stripped of whitespace prior to hashing.
  • For example: "dummy@rapleaf.com" becomes "5376a4b69a80080cc2fa39e143490fc0" when MD5 hashed
    and it becomes "1147e414eec8b785fb760f13f7890a767ffaef6e" when SHA-1 hashed.
Query by Website ID
http://api.rapleaf.com/v3/person/web/<site name>/<profile ID>
  • site name is the website the profile ID is from. This can be one of:
    • bebo (id or name)
    • facebook (id or name)
    • flickr (id or name)
    • friendster (id)
    • hi5 (id)
    • linkedin (id)
    • myspace (id or name)
    • plaxo (id)
    • rapleaf (id)
    • twitter (id or name)
  • profile ID is the user's profile ID on the specified website.
  • For example, the profile ID for the following sites are in bold
    • http://www.facebook.com/john.doe
    • http://www.twitter.com/janedoe
    • http://www.myspace.com/1234567
  • The "rapleaf" website profile ID is the same one returned by Rapleaf's Social Graph API, and the Person ID returned by this API.

Back to Top

Responses

GET Response
HTTP Status Codes
Status Code Description
200 OK Request processed successfully.
202 Accepted This person is currently being searched. Check back shortly and we should have data.
400 Bad Request Invalid email address or Rapleaf ID.
401 Unauthorized API key was not provided or is invalid.
403 Forbidden Your query limit has been exceeded.
Contact developer@rapleaf.com if you would like to increase your limit.
404 Not Found Returned for lookup by hash or site userid. We do not have this person in our system. If you would like better results, consider supplying the email address.
500 Internal Server Error There was an unexpected error on our server. This should be very rare and if you see it please contact developer@rapleaf.com.
Note: This list does not cover all possible HTTP Status Codes that could be returned, only those returned specifically from our API. For example, if the request cannot make it to our API you will likely get a "503 Service Unavailable" response. With this in mind do not code exclusively to handle the response codes listed above.
Response Schema Definitions
XML Schema (.xsd)
Document Type Definition (.dtd)
Example Response
Note: In order to provide rapid turnaround for new emails, the person ID field may initially be empty. The person ID should generally become available within 72 hours. If you are using the person ID field, please make sure your code can handle an empty string. 

<?xml version="1.0" encoding="UTF-8"?>
<person id="1d4c100000000000">
  <basics>
    <name>Test Dummy</name>
    <age>42</age>
    <gender>Male</gender>
    <location>San Francisco, CA, US</location>
    <occupations>
      <occupation job_title="Test Dummy" company="Rapleaf.com"/>
      <occupation job_title="Comedian"/>
    </occupations>
    <universities>
      <university>Berkeley</university>
    </universities>
    <earliest_known_activity>2006-02-23</earliest_known_activity>
    <latest_known_activity>2008-09-25</latest_known_activity>
    <num_friends>42</num_friends>
  </basics>
  <memberships>
    <primary>
      <membership site="bebo.com" exists="false"/>
      <membership site="facebook.com" exists="false"/>
      <membership site="flickr.com" exists="false"/>
      <membership site="friendster.com" profile_url="http://profiles.friendster.com/5563" exists="true"/>
      <membership site="hi5.com" profile_url="http://www.hi5.com/friend/4927" exists="true"/>
      <membership site="linkedin.com" profile_url="http://linkedin.com/profile?viewProfile=&key=31212" exists="true"/>
      <membership site="livejournal.com" exists="false"/>
      <membership site="multiply.com" exists="false"/>
      <membership site="myspace.com" profile_url="http://profile.myspace.com/index.cfm?fuseaction=user.viewprofile&friendID=26448756" exists="true" num_friends="42"/>
      <membership site="myyearbook.com" exists="false"/>
      <membership site="plaxo.com" exists="true"/>
      <membership site="twitter.com" exists="false"/>
    </primary>
    <supplemental>
      <membership site="amazon.com" exists="true"/>
      <membership site="amazon.com/gp/registry/wishlist" profile_url="http://www.amazon.com/gp/registry/registry.html?type=wishlist&id=D5Z2DTHWZQ9Q" exists="true"/>
      <membership site="ecademy.com" profile_url="http://www.ecademy.com/account.php?sha=1a886d0cf" exists="true"/>
      <membership site="flixster.com" profile_url="http://www.flixster.com/user/dummy" image_url="http://images.flixster.com/profile/dummy.jpg" exists="true"/>
      <membership site="ringo.com" exists="true"/>
      <membership site="tickle.com" exists="true"/>
      <membership site="tribe.com" profile_url="http://people.tribe.net/208cdbb3-1ac8a2886" exists="true"/>
      <membership site="tribe.com" profile_url="http://people.tribe.net/a8b373d1-208c3b960" exists="true"/>
      <membership site="yelp.com" profile_url="http://www.yelp.com/user_details?userid=DdfDOLCAA" exists="true"/>
    </supplemental>
  </memberships>
</person>
Memberships Section
Note: <supplemental> memberships only includes tags with exists="true"
Attribute Description
site The url of the site (without the "www.")
exists One of four values:
"true" - the person is a member
"false" - the person is not a member
"tbd" - the person has not been searched for yet, but will be soon
"unknown" - the person has not been searched for yet and we are not currently searching this site
Note: Memberships that have been made private by their owners will be shown as "false".
profile_url The url of the person's profile. This attribute is only present when exists="true" and we know the profile url.
image_url The url of the person's profile image. This attribute is only present when exists="true" and we know the profile image url.
num_friends The number of friends the person has on this site. This attribute is only present when exists="true" and we know the number of friends.
Back to Top

Client Libraries
These libraries make it even easier for you to integrate the Person API functionality into your Python and Ruby applications. Rapleaf is providing these links as a convenience and cannot take any responsibility for the libraries.

Help
For testing we recommend using a helpful Firefox Add-on called Modify Headers which lets you set the HTTP headers of your web requests. By setting the Authorization header to your API Key you can experiment with API requests within your browser.

You can learn more about the basic principles of REST on Wikipedia.
For a more in depth understanding we recommend RESTful Web Services by Leonard Richardson and Sam Ruby.

Please email questions to Rapleaf Developer Support.

Back to Top