API Documentation

API Concepts

Registration

In order to access the BeenVerified API you simply need sign up for a BeenVerified account and register for a developer API key. A user may register multiple applications but each application needs its own API key.

Getting Authorization From A User - OAuth

In order for an application to gain access to a user’s data, the user needs to grant that application access. BeenVerified utilizes the OAuth Protocol in order for our users to give access to a third party application without requiring them to give up their username and password. OAuth can be thought of as a valet key; it allows a user to give limited access to their data, yet it doesn't require them to relinquish their login credentials.

The following subsections discuss some OAuth concepts and how it is utilized within the BeenVerified framework.

Terminology

  • Consumer: That’s you… well your website or application actually
  • Provider: That’s us, the “Provider” of BeenVerified data
  • Request Token: A unique key used to get the End User’s permission to access their data
  • Access Token: Once an End User has granted the Consumer permission to access their data, the Consumer swaps the request token for an access token. This token is used for all subsequent API requests on behalf of this user.
  • End User: That’s BeenVerified user who wants to share their data with your website or application
  • Developer API Key & Secret: That’s what you need to use to sign your requests.

BeenVerified Authentication Flow

  1. Your app asks BeenVerified for a request token
  2. BeenVerified creates and sends back a request token to your app. Your app needs to store that request token and link it to your user
  3. Your app then redirects your user to BeenVerified to authenticate and authorize access for your app
  4. The user authenticates and authorizes the request token
  5. BeenVerified then redirects back to your app (through a callback url) notifying your app of their approval
  6. Now that your app knows that permission has been granted for that token, your app requests an exchange of the request token for an access token and stores it in it’s database
  7. You use that access token for all API calls for that user

BeenVerified API Flow

Resources

Websites and Articles on OAuth

We suggest that you use one of the existing OAuth Libraries to manage this portion of the API process. As of this writing there are libraries for the following languages:

  • C#
  • ColdFusion
  • Objective-C
  • Java
  • Javascript
  • Jifty
  • PERL
  • Python
  • Ruby

You can access these libraries from the oauth code website or the oauth google code repository

Code Libraries

There is already a Ruby Library that wraps both OAuth and BeenVerified's API. Click here to see the project's page. BeenVerified will release and link to more code libraries which encapsulate many of the ideas and flows documented here.

REST

The BeenVerified API has been designed to be RESTful. REST takes advantage of the HTTP verbs such as GET, PUT, POST and DELETE and unique URIs to represent resources. The BeenVerified API utilizes only the GET method at this time as it is a Read-Only API.

An example request to get a users profile: GET https://api.beenverified.com/rest/1.0/user/show.xml

HTTP Requests

The base URL for all HTTP requests is: https://api.beenverified.com/rest/1.0/

HTTP Status Codes

The BeenVerified API provides the proper response codes to each call. If there is an error we also provide error messages in the body of the response

Rate Limiting

Each application will get 2000 calls per day. Once that limit has been reached BeenVerified may refuse to answer any requests for the remainder of the day. If your needs are greater than this please contact api@beenverified.com in order to speak with our API team to establish a higher limit.

Encoding

The API expects all requests in UTF-8 encoding

API Calls

Below are all the types of requests and sample XML responses that they invoke.

User

This call will get a full user profile in XML with all credentials and their details

GET https://api.beenverified.com/api/rest/1.0/user/show.xml?full=true 


<?xml version="1.0" encoding="UTF-8"?>
<user>
  <link_back>http://www.beenverifed.com/personas/XXXXXXXX</link_back>
  <credentials>
    <identities>
      <identity id="2">
        <first_name>Jason</first_name>
        <last_name>Amster</last_name>
        <middle_name></middle_name>
        <suffix></suffix>
        <verified_on>09/26/2007</verified_on>
        <source></source>
        <notes></notes>
      </identity>
    </identities>
    <educations>
      <education id="1">
        <school>Rutgers University</school>
        <major>Computer Science</major>
        <minor></minor>
        <degree>B.S.</degree>
        <start_date></start_date>
        <graduation_date>2003-06-01</graduation_date>
        <verified_on>09/15/2007</verified_on>
        <source></source>
        <notes></notes>
      </education>
    </educations>
    <work_experiences>
      <work_experience id="1">
         <organization>Big Co. Inc</organization>
         <title>Manager - Interactive Development</title>
         <start_date>2007-08-01</start_date>
         <end_date></end_date>
         <verified_on>09/22/2007</verified_on>
         <source></source>
         <notes>May still work at this organization</notes>
      </work_experience>
      <work_experience id="2">
        <organization>Small Co Inc</organization>
        <title>Asst. Manager - Interactive Development</title>
        <start_date>2002-04-01</start_date>
        <end_date>2007-08-01</end_date>
        <verified_on>09/22/2007</verified_on>
        <source></source>
        <notes></notes>
      </work_experience>
    </work_experiences>
  </credentials>
</user>

This call will get a full user profile in XML with links to all the user's credentials.

GET https://api.beenverified.com/api/rest/user/1.0/show.xml 


<?xml version="1.0" encoding="UTF-8"?>
<user>
  <link_back>http://www.beenverified.com/personas/XXXXXXXX</link_back>
  <credentials>
    <identities>
      <identity id="1">
        <url>/rest/1.0/identity/1</url>
      </identity>
    </identities>
    <educations>
      <education id="1">
        <url>/rest/1.0/education/1</url>
      </education>
    </educations>
    <work_experiences>
      <work_experience id="1">
        <url>/rest/1.0/work_experience/1</url>
      </work_experience>
      <work_experience id="2">
      	<url>/rest/1.0/work_experience/2</url>
      </work_experience>
    </work_experiences>
  </credentials>
</user>

Identity

GET https://api.beenverified.com/api/rest/1.0/identities.xml


<xml>
  <identities>
    <identity id="1">
      <first_name>William</first_name>
      <last_name>Clinton</last_name>
      <middle_name>Jefferson</middle_name>
      <suffix></suffix>
      <verified_on>09/26/2007</verified_on>
      <source></source>
      <notes></notes>
    </identity>
  </identities>
</xml>

GET https://api.beenverified.com/api/rest/1.0/identity/[:ID].xml


<xml>
<identity id="1">
  <first_name>William</first_name>
  <last_name>Clinton</last_name>
  <middle_name>Jefferson</middle_name>
  <suffix></suffix>
  <verified_on>09/26/2007</verified_on>
  <source></source>
  <notes></notes>
</identity>
</xml>

Education

GET https://api.beenverified.com/api/rest/1.0/educations.xml


<xml>
  <educations>
    <education id="1">
      <school>Rutgers University</school>
      <major>Computer Science</major>
      <minor></minor>
	  <degree>B.S.</degree>
      <start_date></start_date>
      <graduation_date>2003-06-01</graduation_date>
      <verified_on>09/15/2007</verified_on>
      <source></source>
      <notes></notes>
    </education>
  </educations>
</xml>

GET https://api.beenverified.com/api/rest/1.0/education/[:ID].xml


<xml>
<education id="1">
  <school>Rutgers University</school>
  <major>Computer Science</major>
  <minor></minor>
  <degree>B.S.</degree>
  <start_date></start_date>
  <graduation_date>2003-06-01</graduation_date>
  <verified_on>09/15/2007</verified_on>
  <source></source>
  <notes></notes>
</education>
</xml>

Work Experience

GET https://api.beenverified.com/api/rest/1.0/work_experiences.xml


<xml>
 <work_experiences>
   <work_experience id="1">
     <organization>Big Co. Inc.</organization>
     <title>Manager - Interactive Development</title>
     <start_date>2004-08-01</start_date>
     <end_date>2007-08-01</end_date>
     <verified_on>09/22/2007</verified_on>
     <source></source>
     <notes></notes>
   </work_experience>
 </work_experiences>
</xml>

GET https://api.beenverified.com/api/rest/1.0/work_experience/[:ID].xml


<xml>
<work_experience id="1">
 <organization>Big Company Inc.</organization>
   <title>Manager - Internet Technologies</title>
   <start_date>2004-08-01</start_date>
   <end_date>2007-08-01</end_date>
   <verified_on>09/22/2007</verified_on>
   <source></source>
   <notes></notes>
</work_experience>
</xml>

Certification

GET https://api.beenverified.com/api/rest/1.0/certifications.xml


<xml>
  <certifications>
    <certification id="1">
      <certification_type>Microsoft Certified Technology Specialist (MCTS) </certification_type>
      <issuing_organization>Microsoft, Inc.</issuing_organization>
      <start_date>06/01/2007</start_date>
      <end_date>10/01/2009</end_date>
      <reference_number>42345666</reference_number>
      <verified_on>09/17/2007</verified_on>
      <source></source>
      <notes></notes>
    </certification>
  </certifications>
</xml>

GET https://api.beenverified.com/api/rest/1.0/certification/[:ID].xml


<xml>
  <certification id="1">
    <certification_type>Microsoft Certified Technology Specialist (MCTS) </certification_type>
    <issuing_organization>Microsoft, Inc.</issuing_organization>
    <start_date>06/01/2007</start_date>
    <end_date>10/01/2009</end_date>
    <reference_number>42345666</reference_number>
    <verified_on>09/17/2007</verified_on>
    <source></source>
    <notes></notes>
  </certification>
</xml>

Professional License

GET https://api.beenverified.com/api/rest/1.0/professional_licenses.xml


<xml>
<professional_licenses>
  <professional_license id="1">
    <professional_license_type>Series 7</professional_license_type>
    <issuing_organization>NASD/FINRA</issuing_organization>
    <start_date>04/01/2006</start_date>
    <end_date>09/01/2009</end_date>
    <reference_number>5130687</reference_number>
    <verified_on>09/17/2007</verified_on>
    <source>NASD/FINRA</source>
    <notes></notes>
  </professional_license>
</professional_licenses>
</xml>

GET https://api.beenverified.com/api/rest/1.0/professional_license/[:ID].xml


<xml>
  <professional_license id="1">
    <professional_license_type>Series 7</professional_license_type>
    <issuing_organization>NASD/FINRA</issuing_organization>
    <start_date>04/01/2006</start_date>
    <end_date>09/01/2009</end_date>
    <reference_number>5130687</reference_number>
    <verified_on>09/17/2007</verified_on>
    <source>NASD/FINRA</source>
    <notes></notes>
  </professional_license>
</xml>

Personal Reference

GET https://api.beenverified.com/api/rest/1.0/personal_references.xml


<xml>
<personal_reference id="1">
  <source>Big Company Inc., CEO</source>
  <relationship>Previous Employer</relationship>
  <start_date>04/01/2003</start_date>
  <end_date></end_date>
  <comments>Hard-worker, intelligent, good communication skills</comments>
  <verified_on>09/17/2007</verified_on>
  <source></source>
  <notes></notes>
</personal_reference>
</xml>

GET https://api.beenverified.com/api/rest/1.0/personal_reference/[:ID].xml


<xml>
<personal_reference id="1">
  <source>Big Company Inc., CEO</source>
  <relationship>Previous Employer</relationship>
  <start_date>04/01/2003</start_date>
  <end_date></end_date>
  <comments>Hard-worker, intelligent, good communication skills</comments>
  <verified_on>09/17/2007</verified_on>
  <source></source>
  <notes></notes>
</personal_reference>
</xml>

Email

GET https://api.beenverified.com/api/rest/1.0/emails.xml


<xml>
<emails>
  <email id="1">
    <email_address>email@domain.com</email_address>
    <verified_on>09/15/2007</verified_on>
    <source></source>
    <notes></notes>
  </email>
</emails>
</xml>

GET https://api.beenverified.com/api/rest/1.0/email/[:ID].xml


<xml>
<email id="1">
  <email_address>email@domain.com</email_address>
  <verified_on>09/15/2007</verified_on>
  <source></source>
  <notes></notes>
</email>
</xml>

Web Site

GET https://api.beenverified.com/api/rest/1.0/web_sites.xml


<xml>
  <web_sites>
    <web_site id="1">
      <site_uri>http://claimid.com/yourusername</site_uri>
      <verified_on>04/16/2008</verified_on>
      <source></source>
      <notes></notes>
    </web_site>
  </web_sites>
</xml>

GET https://api.beenverified.com/api/rest/1.0/web_site/[:ID].xml


<xml>
<web_site id="1">
  <site_uri>http://claimid.com/yourusername</site_uri>
  <verified_on>04/16/2008</verified_on>
  <source></source>
  <notes></notes>
</web_site>
</xml>


Code Libraries