release 2.0 · talentiq documentation, release 2.0.0 1.4request object all requests to the api must...

talentiq DocumentationRelease 2.0.0

Tim Neumann

March 15, 2016

Contents

1 Contents 31.1 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Response Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Rate Limiting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.4 Request Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.5 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.6 Webhooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171.7 Likelihood . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

i

talentiq Documentation, Release 2.0.0

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

Contents 1


2 Contents

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: 12345

If using cURL to make requests, the following is how you set your header:

curl -H 'x-api-key: 12345' https://api.talentiq.co/v2/person

1.2 Response Codes

Our API returns standard HTTP success or error status codes. For errors, we will also include extra information aboutwhat went wrong encoded in the response as JSON. The various HTTP status codes we might return are listed below.

Response Code Meaning200 OK202 Lookup performed.400 Bad Request403 Invalid API Key404 Data Not Found422 Invalid query sent429 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 haveimplemented rate limits on a per key basis. Following the lead of Twitter, and Github, whose APIs both providevaluable information regarding rate limits, we have added the following headers to every response:

Header DescriptionX-RateLimit-Limit The rate limit associated with your API key (calls per minute)X-RateLimit-Reset The amount of time in seconds until your rate limit resetsX-RateLimit-Remaining The number of calls before you’ve reached your rate limit

3


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": "http://domain.com/person","profiles": [

"http://linkedin.com/in/seanthorne","http://twitter.com/seanthorne5"

],"emails": [

"[email protected]","[email protected]"

],"experience": [

{"company":"talentiq", "title":"CEO"},{"company": "yoyodyne", "title": "flatware sanitization engineer"}

],"skills:" [

"business","marketing"

],"websites": [

"http://seanthorne.com","http://talentiq.co"

],"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


1.4.1 Parameters

The POST body accepts the following parameters

Parameter Descriptionname The name of the person being searched for (string).emails All emails 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).

1.4.2 Request Schema

The following is the JSON schema for API requests.

{"$schema": "http://json-schema.org/draft-04/schema#","title": "API Scheme for Search Params","type": "object","additionalProperties": false,"properties": {"name": {

"type": "string","description": "The name of the person being searched for."

},"webhookUrl": {

"type": "string","description": "Webhook URL"

},"start": {

"type": "string","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": {

"type": "string","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": {

"type": "string","description": "URL (as per RFC 3986) to your website, e.g. personal homepage"

}},

1.4. Request Object 5


"emails": {"type": "array","description": "Array containing all emails associated with the user.","additionalItems": false,"uniqueItems": true,"maxItems": 5,"items": {

"type": "string","description": "Email addresses associated with the user.","format": "email"

}},"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": {

"type": "string","description": "The URL to the person's social profile."

}},"experience": {


"type": "object","additionalProperties": true,"properties": {"company": {"type": "string","description": "Company associated with the user e.g. Facebook"

},"title": {

"type": "string","description": "Title associated with the user at the company e.g. Software Engineer"

}



}}

},"skills": {

"type": "array","description": "Skills utilized in the job.","additionalItems": false,"uniqueItems": true,"maxItems": 10,"items": {

"type": "string","description": "e.g. Microsoft Office"

}},"education": {


"type": "object","additionalProperties": true,"properties": {"institution": {"type": "string","description": "e.g. Massachusetts Institute of Technology"

},"major": {

"type": "string","description": "e.g. Arts"

},"degree": {

"type": "string","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 totalnumber of persons matching the query is listed in the response.

1.5. Responses 7


1.5.1 Response Fields

Name Descriptionlikelihood The calculated likelihood scorestatus Response Codefrom The starting index for the lookuptotal The total number of results found.requestId Request Identificationresponse The person object, containing all details about the requested person

1.5.2 Example Response

{"likelihood": 10,"total": 1,"status": 200,"error": null,"from": 1,"requestId": "0d177415-65a8-4dbe-b58b-fd958b4aa14b","person": {

"basics": {"summary": "Interested in solving the hardest problems the enterprise is facing.","tagline": null,"industry": "Computer Software","picture": "https:\/\/media.licdn.com\/mpr\/mpr\/shrinknp_200_200\/p\/1\/000

\/196\/116\/170b82b.jpg","phone": null,"phoneNumbers": [

],"additionalInfo": null,"photos": [{"network": "linkedin","additionalProperties": {

},"url": "https:\/\/d2ojpxxtu63wzl.cloudfront.net\/static\/88cde513f7a4728ac2d6e3fca

1562423_8055d777ecb277c7f3daeee8e882afcbcd85a40bf3276e3542dc32927ab68952"},{"network": "twitter","additionalProperties": {

},"url": "https:\/\/d2ojpxxtu63wzl.cloudfront.net\/static\/a0ba921f46704efbb49dfc189

8cb0983_7ee6b5c06eef7478bc3b4b45b926cbdae3248480fe5a80aa578ddf067aa78647"},{

"network": "twitter","additionalProperties": {

},"url": "https:\/\/d2ojpxxtu63wzl.cloudfront.net\/static\/43d1de1adac03e4e1ee26e100

90f0ae5_2ad27c21abcab2fe7f66dbc43d2f0529f95cf07655bbfef0c9c60d56012c6d15"}



],"additionalProperties": {

},"profiles": [{"network": "linkedin","additionalProperties": {

},"url": "https:\/\/www.linkedin.com\/in\/seanthorne","username": "\/in\/seanthorne"

},{


},"url": "https:\/\/twitter.com\/talent_iq","username": "talent_iq"

},{

"network": "linkedin","additionalProperties": {

},"url": "https:\/\/www.linkedin.com\/in\/seanthorne","username": "seanthorne"

},{

"network": "klout","additionalProperties": {

},"url": "http:\/\/klout.com\/user\/id\/63050410339185570","username": null

},{

"network": "gravatar","additionalProperties": {

},"url": "https:\/\/gravatar.com\/thirdpartysports","username": "thirdpartysports"

},{

"network": "angellist","additionalProperties": {

},"url": "https:\/\/angel.co\/sean-thorne-1","username": "sean-thorne-1"

},{


},

1.5. Responses 9


"url": "https:\/\/twitter.com\/SeanThorne5","username": "SeanThorne5"

},{

"network": "gravatar","additionalProperties": {

},"url": "https:\/\/gravatar.com\/seanthorne5","username": "seanthorne5"

}],"url": null,"email": null,"locations": [{"postOfficeBox": null,"extendedAddress": null,"postalCode": null,"countryName": "United States","streetAddress": null,"additionalProperties": {

},"locality": "San Francisco","region": "California"

}],"aliases": ["Sean Thorne","Frankie Thorne"

],"title": "Co-founder, TalentIQ","websites": ["http:\/\/www.talentiq.co","http:\/\/www.seanthorne.com","https:\/\/medium.com\/@SeanThorne5","http:\/\/seanthorne.com"

],"emails": [{

"isVerified": false,"additionalProperties": {

},"email": "[email protected]"

},{



},{





}],"name": "Sean Thorne","location": {"postOfficeBox": null,"extendedAddress": null,"postalCode": null,"countryName": "United States","streetAddress": null,"additionalProperties": {

},"locality": "San Francisco","region": "California"

}},"volunteer": [

],"patents": [

],"certification": [

],"awards": [

{"summary": "http:\/\/uoresearch.uoregon.edu\/content\/accelerating-innovation-

campus-and-willamette-angel-conference","awarder": "Willamette Angel Conference","additionalProperties": {

},"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 32

1.5. Responses 11


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": [

{"additionalProperties": {

},"level": null,"years": null,"name": "Entrepreneurship"

},{"additionalProperties": {

},"level": null,"years": null,"name": "Start-ups"


},"level": null,"years": null,"name": "Management"


},"level": null,"years": null,"name": "Social Media Marketing"


},"level": null,"years": null,"name": "Strategic Partnerships"




},"level": null,"years": null,"name": "Fundraising"


},"level": null,"years": null,"name": "Public Speaking"


},"level": null,"years": null,"name": "Strategy"


},"level": null,"years": null,"name": "Social Media"


},"level": null,"years": null,"name": "Marketing Communications"


},"level": null,"years": null,"name": "Social Networking"


},"level": null,"years": null,"name": "Mobile Devices"

},{

1.5. Responses 13


"additionalProperties": {

},"level": null,"years": null,"name": "Time Management"


},"level": null,"years": null,"name": "Idea Generation"


},"level": null,"years": null,"name": "Mobile Marketing"


},"level": null,"years": null,"name": "SEO"


},"level": null,"years": null,"name": "Photoshop"


},"level": null,"years": null,"name": "Project Management"


},"level": null,"years": null,"name": "Networking"




},"level": null,"years": null,"name": "SaaS"


},"level": null,"years": null,"name": "Marketing Strategy"

}],"experience": [

{"company": "TalentIQ","summary": "TalentIQ takes the massive quantities of obsolete and inaccurate data

that enterprise recruiting, sales, and marketing departments haveaccumulated, and makes it usable again, by updating it with current,actionable information. We are the only existing intelligence API thatenriches and updates your data on a weekly basis + ATS, CRM, and MASdatabase integrations to keep candidate or lead profiles updated. +Enterprise API to power applications, features, and product ideas andgoals. We are trusted by 14 public companies, like eBay, ARM, Randstad,and Teksystems & we are backed by leading Silicon Valley investors.Request a demo: [email protected]",

"salary": null,"startDate": "2015","endDate": null,"highlights": [


},"url": "https:\/\/www.linkedin.com\/company\/talentiq?trk=ppro_cprof","title": "Co-founder & CEO","skills": [

],"location": {

"postOfficeBox": null,"extendedAddress": null,"postalCode": null,"countryName": null,"streetAddress": null,"additionalProperties": {

},"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


https:\/\/www.youtube.com\/watch?v=7gL7yIVXuzE","salary": null,"startDate": "2012","endDate": "2015","highlights": [


},"url": "https:\/\/www.linkedin.com\/company\/hallspot?trk=ppro_cprof","title": "Co-founder","skills": [

],"location": {



}},{"company": "DateMySchool","summary": null,"salary": null,"startDate": "2012","endDate": "2012","highlights": [


},"url": "https:\/\/www.linkedin.com\/company\/datemyschool?trk=ppro_cprof","title": "Marketing Manager","skills": [

],"location": {



}}



],"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 createdon 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 completedaggregating data for the given request. This saves you the trouble of having to check back later. The requestId will bepart of the JSON data, allowing you to easily match the original request to the updated data. If we were still unable toaggregate 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 likelyyou’re getting what you’re looking for. Our score is on a 1 - 10 scale with 10 being a very high probability match. Thelikelihood 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 andresponse, and builds the likelihood score. The person you were looking for may have a low likelihood, but that onlymeans we didn’t have a lot to work with (e.g., small amount of parameters) in order to guarantee the match.

1.6. Webhooks 17

release 2.0 · talentiq documentation, release 2.0.0 1.4request object all requests to the api must...

Documents