# 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"}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.madkudu.com/legacy-api/demographics-person-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.