# Demographics Person API

## Lookup person by email

> Our Person API lets you lookup a person profile via an email address. It returns the predictive customer fit of the lead (aka. demographics score), the top signals behind this score (ie. why is this lead a good fit or not), and some light demographics information (eg. type of email, spam detection, number of employees, industry, etc.).

```json
{"openapi":"3.1.0","info":{"title":"MadKudu Legacy API","version":"0.0.0"},"tags":[{"name":"Persons"}],"servers":[{"url":"https://api.madkudu.com","description":"Legacy API server","variables":{}}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"Basic"}},"schemas":{"Services.Persons.PersonLookupResponse":{"type":"object","required":["object_type","email","properties"],"properties":{"object_type":{"allOf":[{"$ref":"#/components/schemas/Common.Models.ObjectType"}],"description":"Object type identifier"},"email":{"type":"string","description":"Person email"},"properties":{"allOf":[{"$ref":"#/components/schemas/Services.Persons.PersonProperties"}],"description":"Person properties"},"company":{"allOf":[{"$ref":"#/components/schemas/Services.Persons.CompanyInfo"}],"description":"Associated company information"}},"description":"Person lookup response"},"Common.Models.ObjectType":{"type":"string","enum":["company","person"],"description":"Object type identifier"},"Services.Persons.PersonProperties":{"type":"object","properties":{"first_name":{"type":"string","description":"First name of the person"},"last_name":{"type":"string","description":"Last name of the the person"},"domain":{"type":"string","description":"The domain associated with this email address"},"is_student":{"type":"boolean","description":"true if the email is identified as a student email"},"is_spam":{"type":"boolean","description":"true if the email is identified as a spam email"},"is_personal_email":{"type":"boolean","description":"true if the email is identified as a personal (or disposable) email address (e.g. gmail.com)"},"customer_fit":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CustomerFit"}],"description":"The standard MadKudu customer fit fields"},"predicted_value":{"type":"number","format":"double","description":"(Optional) The value of a lead before they have reached the end of the funnel (aka made a purchase), based on the historical value of similar leads who have made the purchase."}},"description":"Person properties containing all person information"},"Common.Models.CustomerFit":{"type":"object","required":["segment","score","top_signals","top_signals_formated"],"properties":{"segment":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CustomerFitSegment"}],"description":"The standard MadKudu Customer Fit segment which is either \"low\", \"medium\", \"good\" or \"very good\""},"score":{"type":"number","format":"double","minimum":0,"maximum":100,"description":"The standard MadKudu Customer Fit score which ranges from 0 to 100"},"top_signals":{"type":"array","items":{"$ref":"#/components/schemas/Common.Models.Signal"},"description":"The standard MadKudu Customer Fit signals presented in array format where each signal line is shown in name, value and type"},"top_signals_formated":{"type":"string","description":"The standard MadKudu Customer Fit signals presented all in one string"}},"description":"Customer fit analysis with score and signals"},"Common.Models.CustomerFitSegment":{"type":"string","enum":["low","medium","good","very good"],"description":"Customer fit segment values"},"Common.Models.Signal":{"type":"object","required":["name","value","type"],"properties":{"name":{"type":"string","description":"Name of the signal"},"value":{"anyOf":[{"type":"string"},{"type":"integer","format":"int32"},{"type":"number","format":"double"}],"description":"Value of the signal (can be string or number)"},"type":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SignalType"}],"description":"Type of signal impact"}},"description":"Individual signal contributing to customer fit score"},"Common.Models.SignalType":{"type":"string","enum":["positive","negative"],"description":"Signal type indicating positive or negative impact"},"Services.Persons.CompanyInfo":{"type":"object","required":["properties"],"properties":{"properties":{"allOf":[{"$ref":"#/components/schemas/Services.Persons.CompanyInfoProperties"}],"description":"Company properties"}},"description":"Company information associated with person"},"Services.Persons.CompanyInfoProperties":{"type":"object","properties":{"name":{"type":"string","description":"Company name"},"domain":{"type":"string","description":"Company domain"},"location":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Location"}],"description":"Company headquarters location"},"number_of_employees":{"type":"integer","format":"int32","description":"Number of employees"},"industry":{"type":"string","description":"Industry classification"},"predicted_value":{"type":"number","format":"double","description":"Predicted value of the company"}},"description":"Company properties within person response"},"Common.Models.Location":{"type":"object","properties":{"state":{"type":"string","description":"The headquarters' state name"},"state_code":{"type":"string","description":"The headquarters' two-character state code"},"country":{"type":"string","description":"The headquarters's country"},"country_code":{"type":"string","description":"The headquarters's two-character country code"},"tags":{"type":"array","items":{"type":"string"},"description":"An array of tags describing the location"}},"description":"Geographic location information"},"Common.Errors.ValidationError":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Error message"},"details":{"type":"string","description":"Invalid parameter details"}},"description":"Validation error for request parameters"},"Common.Errors.AuthenticationError":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Error message"}},"description":"Authentication error"},"Common.Errors.NotFoundError":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Error message"}},"description":"Resource not found error"},"Common.Errors.RateLimitError":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Error message"},"details":{"type":"string","description":"Rate limit details"}},"description":"Rate limit exceeded error"},"Common.Errors.InternalServerError":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Error message"}},"description":"Internal server error"}}},"paths":{"/v1/persons":{"get":{"operationId":"Persons_lookupPerson","summary":"Lookup person by email","description":"Our Person API lets you lookup a person profile via an email address. It returns the predictive customer fit of the lead (aka. demographics score), the top signals behind this score (ie. why is this lead a good fit or not), and some light demographics information (eg. type of email, spam detection, number of employees, industry, etc.).","parameters":[{"name":"email","in":"query","required":true,"description":"The email of the lead you would like to retrieve","schema":{"type":"string"},"explode":false}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Services.Persons.PersonLookupResponse"}}}},"400":{"description":"The server could not understand the request due to invalid syntax.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ValidationError"}}}},"401":{"description":"Access is unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.AuthenticationError"}}}},"404":{"description":"The server cannot find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.NotFoundError"}}}},"429":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.RateLimitError"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.InternalServerError"}}}}},"tags":["Persons"]}}}}
```

## Lookup person with enriched payload

> This API endpoint lets you provide your own enriched person data. It's used to allow very high volume tenants to send us directly the Clearbit payload for us to score.

```json
{"openapi":"3.1.0","info":{"title":"MadKudu Legacy API","version":"0.0.0"},"tags":[{"name":"Persons"}],"servers":[{"url":"https://api.madkudu.com","description":"Legacy API server","variables":{}}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"Basic"}},"schemas":{"Services.Persons.PersonLookupResponse":{"type":"object","required":["object_type","email","properties"],"properties":{"object_type":{"allOf":[{"$ref":"#/components/schemas/Common.Models.ObjectType"}],"description":"Object type identifier"},"email":{"type":"string","description":"Person email"},"properties":{"allOf":[{"$ref":"#/components/schemas/Services.Persons.PersonProperties"}],"description":"Person properties"},"company":{"allOf":[{"$ref":"#/components/schemas/Services.Persons.CompanyInfo"}],"description":"Associated company information"}},"description":"Person lookup response"},"Common.Models.ObjectType":{"type":"string","enum":["company","person"],"description":"Object type identifier"},"Services.Persons.PersonProperties":{"type":"object","properties":{"first_name":{"type":"string","description":"First name of the person"},"last_name":{"type":"string","description":"Last name of the the person"},"domain":{"type":"string","description":"The domain associated with this email address"},"is_student":{"type":"boolean","description":"true if the email is identified as a student email"},"is_spam":{"type":"boolean","description":"true if the email is identified as a spam email"},"is_personal_email":{"type":"boolean","description":"true if the email is identified as a personal (or disposable) email address (e.g. gmail.com)"},"customer_fit":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CustomerFit"}],"description":"The standard MadKudu customer fit fields"},"predicted_value":{"type":"number","format":"double","description":"(Optional) The value of a lead before they have reached the end of the funnel (aka made a purchase), based on the historical value of similar leads who have made the purchase."}},"description":"Person properties containing all person information"},"Common.Models.CustomerFit":{"type":"object","required":["segment","score","top_signals","top_signals_formated"],"properties":{"segment":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CustomerFitSegment"}],"description":"The standard MadKudu Customer Fit segment which is either \"low\", \"medium\", \"good\" or \"very good\""},"score":{"type":"number","format":"double","minimum":0,"maximum":100,"description":"The standard MadKudu Customer Fit score which ranges from 0 to 100"},"top_signals":{"type":"array","items":{"$ref":"#/components/schemas/Common.Models.Signal"},"description":"The standard MadKudu Customer Fit signals presented in array format where each signal line is shown in name, value and type"},"top_signals_formated":{"type":"string","description":"The standard MadKudu Customer Fit signals presented all in one string"}},"description":"Customer fit analysis with score and signals"},"Common.Models.CustomerFitSegment":{"type":"string","enum":["low","medium","good","very good"],"description":"Customer fit segment values"},"Common.Models.Signal":{"type":"object","required":["name","value","type"],"properties":{"name":{"type":"string","description":"Name of the signal"},"value":{"anyOf":[{"type":"string"},{"type":"integer","format":"int32"},{"type":"number","format":"double"}],"description":"Value of the signal (can be string or number)"},"type":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SignalType"}],"description":"Type of signal impact"}},"description":"Individual signal contributing to customer fit score"},"Common.Models.SignalType":{"type":"string","enum":["positive","negative"],"description":"Signal type indicating positive or negative impact"},"Services.Persons.CompanyInfo":{"type":"object","required":["properties"],"properties":{"properties":{"allOf":[{"$ref":"#/components/schemas/Services.Persons.CompanyInfoProperties"}],"description":"Company properties"}},"description":"Company information associated with person"},"Services.Persons.CompanyInfoProperties":{"type":"object","properties":{"name":{"type":"string","description":"Company name"},"domain":{"type":"string","description":"Company domain"},"location":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Location"}],"description":"Company headquarters location"},"number_of_employees":{"type":"integer","format":"int32","description":"Number of employees"},"industry":{"type":"string","description":"Industry classification"},"predicted_value":{"type":"number","format":"double","description":"Predicted value of the company"}},"description":"Company properties within person response"},"Common.Models.Location":{"type":"object","properties":{"state":{"type":"string","description":"The headquarters' state name"},"state_code":{"type":"string","description":"The headquarters' two-character state code"},"country":{"type":"string","description":"The headquarters's country"},"country_code":{"type":"string","description":"The headquarters's two-character country code"},"tags":{"type":"array","items":{"type":"string"},"description":"An array of tags describing the location"}},"description":"Geographic location information"},"Common.Errors.ValidationError":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Error message"},"details":{"type":"string","description":"Invalid parameter details"}},"description":"Validation error for request parameters"},"Common.Errors.AuthenticationError":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Error message"}},"description":"Authentication error"},"Common.Errors.RateLimitError":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Error message"},"details":{"type":"string","description":"Rate limit details"}},"description":"Rate limit exceeded error"},"Common.Errors.InternalServerError":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Error message"}},"description":"Internal server error"},"Services.Persons.PersonLookupWithPayloadRequest":{"type":"object","required":["email","person","company"],"properties":{"email":{"type":"string","description":"Person email"},"person":{"allOf":[{"$ref":"#/components/schemas/Common.Models.ClearbitPerson"}],"description":"Clearbit person payload"},"company":{"allOf":[{"$ref":"#/components/schemas/Common.Models.ClearbitCompany"}],"description":"Clearbit company payload"}},"description":"Person lookup with payload request"},"Common.Models.ClearbitPerson":{"type":"object","properties":{"id":{"type":"string","description":"Person ID"},"name":{"allOf":[{"$ref":"#/components/schemas/Common.Models.ClearbitPersonName"}],"description":"Name components"},"email":{"type":"string","description":"Email address"},"gender":{"type":"string","description":"Gender"},"location":{"type":"string","description":"Location string"},"timeZone":{"type":"string","description":"Time zone"},"utcOffset":{"type":"integer","format":"int32","description":"UTC offset"},"geo":{"allOf":[{"$ref":"#/components/schemas/Common.Models.GeoLocation"}],"description":"Geographic location"},"bio":{"type":"string","description":"Biography"},"site":{"type":"string","description":"Website URL"},"avatar":{"type":"string","description":"Avatar URL"},"employment":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Employment"}],"description":"Employment information"},"facebook":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SocialProfile"}],"description":"Facebook profile"},"github":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SocialProfile"}],"description":"GitHub profile"},"twitter":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SocialProfile"}],"description":"Twitter profile"},"linkedin":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SocialProfile"}],"description":"LinkedIn profile"},"googleplus":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SocialProfile"}],"description":"Google+ profile"},"aboutme":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SocialProfile"}],"description":"About.me profile"},"gravatar":{"allOf":[{"$ref":"#/components/schemas/Common.Models.GravatarProfile"}],"description":"Gravatar profile"},"fuzzy":{"type":"boolean","description":"Fuzzy match indicator"},"emailProvider":{"type":"boolean","description":"Email provider flag"},"indexedAt":{"type":"string","description":"Index timestamp"}},"description":"Complete Clearbit person payload"},"Common.Models.ClearbitPersonName":{"type":"object","properties":{"fullName":{"type":"string","description":"Full name"},"givenName":{"type":"string","description":"Given name (first name)"},"familyName":{"type":"string","description":"Family name (last name)"}},"description":"Clearbit person name structure"},"Common.Models.GeoLocation":{"type":"object","properties":{"streetNumber":{"type":"string","description":"Street number"},"streetName":{"type":"string","description":"Street name"},"subPremise":{"type":"string","description":"Sub-premise information"},"city":{"type":"string","description":"City name"},"postalCode":{"type":"string","description":"Postal code"},"state":{"type":"string","description":"State name"},"stateCode":{"type":"string","description":"State code"},"country":{"type":"string","description":"Country name"},"countryCode":{"type":"string","description":"Country code"},"lat":{"type":"number","format":"double","description":"Latitude coordinate"},"lng":{"type":"number","format":"double","description":"Longitude coordinate"}},"description":"Detailed geographic coordinates"},"Common.Models.Employment":{"type":"object","properties":{"domain":{"type":"string","description":"Company domain"},"name":{"type":"string","description":"Company name"},"title":{"type":"string","description":"Job title"},"role":{"type":"string","description":"Role category"},"seniority":{"type":"string","description":"Seniority level"}},"description":"Employment information"},"Common.Models.SocialProfile":{"type":"object","properties":{"handle":{"type":"string","description":"Social media handle"},"id":{"anyOf":[{"type":"string"},{"type":"integer","format":"int64"}],"description":"Profile ID"},"bio":{"type":"string","description":"Profile bio"},"followers":{"type":"integer","format":"int32","description":"Number of followers"},"following":{"type":"integer","format":"int32","description":"Number of following"},"avatar":{"type":"string","description":"Avatar URL"},"location":{"type":"string","description":"Location"},"site":{"type":"string","description":"Website URL"},"company":{"type":"string","description":"Company"},"blog":{"type":"string","description":"Blog URL"},"statuses":{"type":"integer","format":"int32","description":"Number of statuses"},"favorites":{"type":"integer","format":"int32","description":"Number of favorites"},"likes":{"type":"integer","format":"int32","description":"Number of likes"}},"description":"Social media profile"},"Common.Models.GravatarProfile":{"type":"object","properties":{"handle":{"type":"string","description":"Handle"},"urls":{"type":"array","items":{"type":"string"},"description":"URLs"},"avatar":{"type":"string","description":"Avatar URL"},"avatars":{"type":"array","items":{"$ref":"#/components/schemas/Common.Models.GravatarAvatar"},"description":"Avatar variations"}},"description":"Gravatar profile"},"Common.Models.GravatarAvatar":{"type":"object","properties":{"url":{"type":"string","description":"Avatar URL"},"type":{"type":"string","description":"Avatar type"}},"description":"Gravatar avatar information"},"Common.Models.ClearbitCompany":{"type":"object","properties":{"id":{"type":"string","description":"Company ID"},"name":{"type":"string","description":"Company name"},"legalName":{"type":"string","description":"Legal name"},"domain":{"type":"string","description":"Primary domain"},"domainAliases":{"type":"array","items":{"type":"string"},"description":"Domain aliases"},"site":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CompanySite"}],"description":"Site information"},"category":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CompanyCategory"}],"description":"Category classification"},"tags":{"type":"array","items":{"type":"string"},"description":"Company tags"},"description":{"type":"string","description":"Company description"},"foundedYear":{"type":"integer","format":"int32","description":"Founded year"},"location":{"type":"string","description":"Location string"},"timeZone":{"type":"string","description":"Time zone"},"utcOffset":{"type":"integer","format":"int32","description":"UTC offset"},"geo":{"allOf":[{"$ref":"#/components/schemas/Common.Models.GeoLocation"}],"description":"Geographic location"},"logo":{"type":"string","description":"Logo URL"},"facebook":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SocialProfile"}],"description":"Facebook profile"},"linkedin":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SocialProfile"}],"description":"LinkedIn profile"},"twitter":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SocialProfile"}],"description":"Twitter profile"},"crunchbase":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SocialProfile"}],"description":"Crunchbase profile"},"emailProvider":{"type":"boolean","description":"Email provider flag"},"type":{"type":"string","description":"Company type"},"ticker":{"type":"string","description":"Stock ticker"},"identifiers":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CompanyIdentifiers"}],"description":"Company identifiers"},"phone":{"type":"string","description":"Phone number"},"metrics":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CompanyMetrics"}],"description":"Company metrics"},"indexedAt":{"type":"string","description":"Index timestamp"},"tech":{"type":"array","items":{"type":"string"},"description":"Technology stack"},"parent":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CompanyParent"}],"description":"Parent company"}},"description":"Complete Clearbit company payload"},"Common.Models.CompanySite":{"type":"object","properties":{"phoneNumbers":{"type":"array","items":{"type":"string"},"description":"Phone numbers"},"emailAddresses":{"type":"array","items":{"type":"string"},"description":"Email addresses"}},"description":"Company site information"},"Common.Models.CompanyCategory":{"type":"object","properties":{"sector":{"type":"string","description":"Business sector"},"industryGroup":{"type":"string","description":"Industry group"},"industry":{"type":"string","description":"Industry"},"subIndustry":{"type":"string","description":"Sub-industry"},"sicCode":{"type":"string","description":"SIC code"},"naicsCode":{"type":"string","description":"NAICS code"}},"description":"Company category classification"},"Common.Models.CompanyIdentifiers":{"type":"object","properties":{"usEIN":{"type":"string","description":"US EIN number"}},"description":"Company identifiers"},"Common.Models.CompanyMetrics":{"type":"object","properties":{"alexaUsRank":{"type":"integer","format":"int32","description":"Alexa US rank"},"alexaGlobalRank":{"type":"integer","format":"int32","description":"Alexa global rank"},"employees":{"type":"integer","format":"int32","description":"Number of employees"},"employeesRange":{"type":"string","description":"Employee range"},"marketCap":{"type":"integer","format":"int64","description":"Market cap"},"raised":{"type":"integer","format":"int64","description":"Capital raised"},"annualRevenue":{"type":"integer","format":"int64","description":"Annual revenue"},"estimatedAnnualRevenue":{"type":"string","description":"Estimated annual revenue"},"fiscalYearEnd":{"type":"integer","format":"int32","description":"Fiscal year end month"}},"description":"Company metrics"},"Common.Models.CompanyParent":{"type":"object","properties":{"domain":{"type":"string","description":"Parent company domain"}},"description":"Company parent information"}}},"paths":{"/v1/persons":{"post":{"operationId":"Persons_lookupPersonWithPayload","summary":"Lookup person with enriched payload","description":"This API endpoint lets you provide your own enriched person data. It's used to allow very high volume tenants to send us directly the Clearbit payload for us to score.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Services.Persons.PersonLookupResponse"}}}},"400":{"description":"The server could not understand the request due to invalid syntax.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ValidationError"}}}},"401":{"description":"Access is unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.AuthenticationError"}}}},"422":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ValidationError"}}}},"429":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.RateLimitError"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.InternalServerError"}}}}},"tags":["Persons"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Services.Persons.PersonLookupWithPayloadRequest"}}}}}}}}
```