talentiq Documentation

Transcription

1 talentiq Documentation Release Tim Neumann March 15, 2016

2

3 Contents 1 Contents Authentication Response Codes Rate Limiting Request Object Responses Webhooks Likelihood i

4 ii

5 Welcome to TalentIQ s API! You can use the API to programmatically interact with the TalentIQ data set. All requests should be made over SSL. All request and response bodies, including errors, are encoded in JSON. The purpose of our API is to give your organization mission-critical people data where you need it most. If you d like to see us add an endpoint or feature to the API please contact us Contents 1

6 2 Contents

7 CHAPTER 1 Contents 1.1 Authentication All requests to the API must specify the API key provided to you using the X-Api-Key customer header. For example, if your API key value is 12345, the custom header would be as follows: x-api-key: If using curl to make requests, the following is how you set your header: curl -H 'x-api-key: 12345' Response Codes Our API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON. The various HTTP status codes we might return are listed below. Response Code Meaning 200 OK 202 Lookup performed. 400 Bad Request 403 Invalid API Key 404 Data Not Found 422 Invalid query sent 429 Over Limit 1.3 Rate Limiting In order to protect servers from being overloaded and maintain a higher quality of service to our clients, we have implemented rate limits on a per key basis. Following the lead of Twitter, and Github, whose APIs both provide valuable information regarding rate limits, we have added the following headers to every response: Header X-RateLimit-Limit X-RateLimit-Reset X-RateLimit-Remaining Description The rate limit associated with your API key (calls per minute) The amount of time in seconds until your rate limit resets The number of calls before you ve reached your rate limit 3

8 1.4 Request Object All requests to the API must use POST and send a JSON body specifying the terms to be used in the request. Example: POST /v2/person "name": "Sean Thorne", "start": 5, "webhookurl": " "profiles": [ " " " s": [ "sean@talentiq.co", "sean@gmail.com" "experience": [ "company":"talentiq", "title":"ceo" "company": "yoyodyne", "title": "flatware sanitization engineer" "skills:" [ "business", "marketing" "websites": [ " " "education": [ "institution": "Harvard", "major": "Computer Science" "institution": "MIT", "major": "Dog Training" "aliases": [ "Sean Franklin Thorne", "Frankie Thorne" "locations": [ "locality": "Portland", "region": "Oregon", "postal-code": "97239", "country-name": "US" "locality": "San Francisco", "region": "CA", "country-name": "US" ] 4 Chapter 1. Contents

9 1.4.1 Parameters The POST body accepts the following parameters Parameter Description name The name of the person being searched for (string). s All s associated with the user (array). experience Work experience associated with the user (array of objects). skills Skills associated with the user (array). education Education information associated with the user (array of objects). profiles Social network URLs associated with user (array). websites Websites associated with the user (array) Request Schema The following is the JSON schema for API requests. "$schema": " "title": "API Scheme for Search Params", "type": "object", "additionalproperties": false, "properties": "name": "description": "The name of the person being searched for." "webhookurl": "description": "Webhook URL" "start": "description": "Start location within the result set of paginated returns." "aliases": "type": "array", "description": "Other names the user goes by.", "additionalitems": false, "uniqueitems": true, "maxitems": 5, "items": "description": "Other names the person may go by." "websites": "type": "array", "description": "Personal websites associated with the user.", "additionalitems": false, "uniqueitems": true, "maxitems": 5, "items": "description": "URL (as per RFC 3986) to your website, e.g. personal homepage" 1.4. Request Object 5

10 " s": "type": "array", "description": "Array containing all s associated with the user.", "additionalitems": false, "uniqueitems": true, "maxitems": 5, "items": "description": " addresses associated with the user.", "format": " " "locations": "type": "array", "additionalitems": false, "uniqueitems": true, "maxitems": 5, "items": "properties": "post-office-box": "type": "string" "extended-address": "type": "string" "street-address": "type": "string" "locality": "type": "string" "region": "type": "string" "postal-code": "type": "string" "country-name": "type": "string" "required": ["locality", "region", "country-name" "profiles": "type": "array", "description": "Social network URLs associated with the user.", "additionalitems": false, "uniqueitems": true, "maxitems": 10, "items": "description": "The URL to the person's social profile." "experience": "type": "array", "additionalitems": false, "uniqueitems": true, "maxitems": 10, "items": "type": "object", "additionalproperties": true, "properties": "company": "description": "Company associated with the user e.g. Facebook" "title": "description": "Title associated with the user at the company e.g. Software Engineer" 6 Chapter 1. Contents

11 "skills": "type": "array", "description": "Skills utilized in the job.", "additionalitems": false, "uniqueitems": true, "maxitems": 10, "items": "description": "e.g. Microsoft Office" "education": "type": "array", "additionalitems": false, "uniqueitems": true, "maxitems": 5, "items": "type": "object", "additionalproperties": true, "properties": "institution": "description": "e.g. Massachusetts Institute of Technology" "major": "description": "e.g. Arts" "degree": "description": "e.g. Bachelor" 1.5 Responses Each query will return a single person. If more than one person is found, the most relevant match is returned first. The user can request more matches from the query by incrementing the from parameter in their POST data. The total number of persons matching the query is listed in the response Responses 7

12 1.5.1 Response Fields Name likelihood status from total requestid response Description The calculated likelihood score Response Code The starting index for the lookup The total number of results found. Request Identification The person object, containing all details about the requested person Example Response "likelihood": 10, "total": 1, "status": 200, "error": null, "from": 1, "requestid": "0d a8-4dbe-b58b-fd958b4aa14b", "person": "basics": "summary": "Interested in solving the hardest problems the enterprise is facing.", "tagline": null, "industry": "Computer Software", "picture": " \/196\/116\/170b82b.jpg", "phone": null, "phonenumbers": [ "additionalinfo": null, "photos": [ "network": "linkedin", "url": " _8055d777ecb277c7f3daeee8e882afcbcd85a40bf3276e3542dc32927ab68952" "network": "twitter", "url": " 8cb0983_7ee6b5c06eef7478bc3b4b45b926cbdae fe5a80aa578ddf067aa78647" "network": "twitter", "url": " 90f0ae5_2ad27c21abcab2fe7f66dbc43d2f0529f95cf07655bbfef0c9c60d56012c6d15" 8 Chapter 1. Contents

13 "profiles": [ "network": "linkedin", "url": " "username": "\/in\/seanthorne" "network": "twitter", "url": " "username": "talent_iq" "network": "linkedin", "url": " "username": "seanthorne" "network": "klout", "url": " "username": null "network": "gravatar", "url": " "username": "thirdpartysports" "network": "angellist", "url": " "username": "sean-thorne-1" "network": "twitter", 1.5. Responses 9

14 "url": " "username": "SeanThorne5" "network": "gravatar", "url": " "username": "seanthorne5" "url": null, " ": null, "locations": [ "postofficebox": null, "extendedaddress": null, "postalcode": null, "countryname": "United States", "streetaddress": null, "locality": "San Francisco", "region": "California" "aliases": [ "Sean Thorne", "Frankie Thorne" "title": "Co-founder, TalentIQ", "websites": [ " " " " " s": [ "isverified": false, " ": "sean@talentiq.co" "isverified": false, " ": "deseanthorne@gmail.com" "isverified": false, 10 Chapter 1. Contents

15 " ": "name": "Sean Thorne", "location": "postofficebox": null, "extendedaddress": null, "postalcode": null, "countryname": "United States", "streetaddress": null, "locality": "San Francisco", "region": "California" "volunteer": [ "patents": [ "certification": [ "awards": [ "summary": " "awarder": "Willamette Angel Conference", "date": "May 2013", "title": "2013 Willamette Angel Conference Early Stage Company Winner" "publications": [ "languages": [ "interests": [ "events": [ "organizations": [ "projects": [ "summary": "Created college advice website 100% written by students for students. No longer live, but received over 3M visits, over 250 student writers at Responses 11

16 schools creating content, and readers in 188 countries worldwide.", "startdate": "January 2011", "enddate": "August 2013", "nonprofit": null, "activities": [ "entity": "Welcome to College Freshmen", "role": null, "url": null "references": [ "skills": [ "name": "Entrepreneurship" "name": "Start-ups" "name": "Management" "name": "Social Media Marketing" "name": "Strategic Partnerships" 12 Chapter 1. Contents

17 "name": "Fundraising" "name": "Public Speaking" "name": "Strategy" "name": "Social Media" "name": "Marketing Communications" "name": "Social Networking" "name": "Mobile Devices" 1.5. Responses 13

18 "name": "Time Management" "name": "Idea Generation" "name": "Mobile Marketing" "name": "SEO" "name": "Photoshop" "name": "Project Management" "name": "Networking" 14 Chapter 1. Contents

19 "name": "SaaS" "name": "Marketing Strategy" "experience": [ "company": "TalentIQ", "summary": "TalentIQ takes the massive quantities of obsolete and inaccurate data that enterprise recruiting, sales, and marketing departments have accumulated, and makes it usable again, by updating it with current, actionable information. We are the only existing intelligence API that enriches and updates your data on a weekly basis + ATS, CRM, and MAS database integrations to keep candidate or lead profiles updated. + Enterprise API to power applications, features, and product ideas and goals. We are trusted by 14 public companies, like ebay, ARM, Randstad, and Teksystems & we are backed by leading Silicon Valley investors. Request a demo: sean@talentiq.co", "salary": null, "startdate": "2015", "enddate": null, "highlights": [ "url": " "title": "Co-founder & CEO", "skills": [ "location": "postofficebox": null, "extendedaddress": null, "postalcode": null, "countryname": null, "streetaddress": null, "locality": null, "region": null "company": "Hallspot, Inc", "summary": "CRM for bars and restaurants. Expanded to select west coast college campuses. 800k seed. Angel Conference Presentation: 1.5. Responses 15

20 "salary": null, "startdate": "2012", "enddate": "2015", "highlights": [ "url": " "title": "Co-founder", "skills": [ "location": "postofficebox": null, "extendedaddress": null, "postalcode": null, "countryname": null, "streetaddress": null, "locality": null, "region": null "company": "DateMySchool", "summary": null, "salary": null, "startdate": "2012", "enddate": "2012", "highlights": [ "url": " "title": "Marketing Manager", "skills": [ "location": "postofficebox": null, "extendedaddress": null, "postalcode": null, "countryname": null, "streetaddress": null, "locality": null, "region": null 16 Chapter 1. Contents

21 "education": [ "institution": "University of Oregon", "degree": "", "startdate": "2010", "enddate": "2014", "gpa": null, "highlights": [ "courses": [ "exams": [ ] "url": null, "major": "Entrepreneurship", "location": null 1.6 Webhooks At times the API will be unable to immediately find a match for a given request. When this happens, a job is created on our end to try and aggregate a person, and the requestor is given a 202 HTTP response code. When this happens, there are two ways in which the requestor can obtain the data. First, they can check back later to see if the data is there. The second method is to provide a webhook URL in the request body, containing a URL that accepts JSON post data. When a webhook URL is provided, we will post the entire JSON response to the URL when we have completed aggregating data for the given request. This saves you the trouble of having to check back later. The requestid will be part of the JSON data, allowing you to easily match the original request to the updated data. If we were still unable to aggregate any data on the given user, a 404 response is sent. 1.7 Likelihood Our likelihood score ensures that we are providing the best possible match for your lookup, and shows you how likely you re getting what you re looking for. Our score is on a 1-10 scale with 10 being a very high probability match. The likelihood is calculated based on the parameters given us compared against the result being returned. On our end, an algorithm takes the weight of each item, which changes based on what is present in the request and response, and builds the likelihood score. The person you were looking for may have a low likelihood, but that only means we didn t have a lot to work with (e.g., small amount of parameters) in order to guarantee the match Webhooks 17