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
- Your app asks BeenVerified for a request token
- 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
- Your app then redirects your user to BeenVerified to authenticate and authorize access for your app
- The user authenticates and authorizes the request token
- BeenVerified then redirects back to your app (through a callback url) notifying your app of their approval
- 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
- 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>
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>
