# Demographics Company API

## Lookup company by domain

> Our Company API lets you lookup a company profile via a domain name. It returns the predictive customer fit of the company (aka. demographics score), the top signals behind this score (ie. why is this company a good fit or not), and some light demographics information (eg. number of employees, industry, etc.).

```json
{"openapi":"3.1.0","info":{"title":"MadKudu Legacy API","version":"0.0.0"},"tags":[{"name":"Companies"}],"servers":[{"url":"https://api.madkudu.com","description":"Legacy API server","variables":{}}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"Basic"}},"schemas":{"Services.Companies.CompanyLookupResponse":{"type":"object","required":["object_type","domain","properties"],"properties":{"object_type":{"allOf":[{"$ref":"#/components/schemas/Common.Models.ObjectType"}],"description":"Object type identifier"},"domain":{"type":"string","description":"Company domain"},"properties":{"allOf":[{"$ref":"#/components/schemas/Services.Companies.CompanyProperties"}],"description":"Company properties"}},"description":"Company lookup response"},"Common.Models.ObjectType":{"type":"string","enum":["company","person"],"description":"Object type identifier"},"Services.Companies.CompanyProperties":{"type":"object","properties":{"name":{"type":"string","description":"The name of the company associated with this person"},"domain":{"type":"string","description":"The domain of the company associated with this person"},"location":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Location"}],"description":"The location of the company's headquarters"},"number_of_employees":{"type":"integer","format":"int32","description":"The number of employees at the company"},"industry":{"type":"string","description":"The industry of the company"},"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 an account before they have reached the end of the funnel (aka made a purchase), based on the historical value of similar accounts who have made the purchase."}},"description":"Company properties containing all company information"},"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.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"},"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/companies":{"get":{"operationId":"Companies_lookupCompany","summary":"Lookup company by domain","description":"Our Company API lets you lookup a company profile via a domain name. It returns the predictive customer fit of the company (aka. demographics score), the top signals behind this score (ie. why is this company a good fit or not), and some light demographics information (eg. number of employees, industry, etc.).","parameters":[{"name":"domain","in":"query","required":true,"description":"The domain name of the company 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.Companies.CompanyLookupResponse"}}}},"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":["Companies"]}}}}
```

## Lookup company with enriched payload

> This API endpoint lets you provide your own enriched company data.

```json
{"openapi":"3.1.0","info":{"title":"MadKudu Legacy API","version":"0.0.0"},"tags":[{"name":"Companies"}],"servers":[{"url":"https://api.madkudu.com","description":"Legacy API server","variables":{}}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"Basic"}},"schemas":{"Services.Companies.CompanyLookupResponse":{"type":"object","required":["object_type","domain","properties"],"properties":{"object_type":{"allOf":[{"$ref":"#/components/schemas/Common.Models.ObjectType"}],"description":"Object type identifier"},"domain":{"type":"string","description":"Company domain"},"properties":{"allOf":[{"$ref":"#/components/schemas/Services.Companies.CompanyProperties"}],"description":"Company properties"}},"description":"Company lookup response"},"Common.Models.ObjectType":{"type":"string","enum":["company","person"],"description":"Object type identifier"},"Services.Companies.CompanyProperties":{"type":"object","properties":{"name":{"type":"string","description":"The name of the company associated with this person"},"domain":{"type":"string","description":"The domain of the company associated with this person"},"location":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Location"}],"description":"The location of the company's headquarters"},"number_of_employees":{"type":"integer","format":"int32","description":"The number of employees at the company"},"industry":{"type":"string","description":"The industry of the company"},"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 an account before they have reached the end of the funnel (aka made a purchase), based on the historical value of similar accounts who have made the purchase."}},"description":"Company properties containing all company information"},"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.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"},"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.Companies.CompanyLookupWithPayloadRequest":{"type":"object","required":["domain","company"],"properties":{"domain":{"type":"string","description":"Company domain"},"company":{"allOf":[{"$ref":"#/components/schemas/Common.Models.ClearbitCompany"}],"description":"Clearbit company payload"}},"description":"Company lookup with payload request"},"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.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.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.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/companies":{"post":{"operationId":"Companies_lookupCompanyWithPayload","summary":"Lookup company with enriched payload","description":"This API endpoint lets you provide your own enriched company data.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Services.Companies.CompanyLookupResponse"}}}},"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":["Companies"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Services.Companies.CompanyLookupWithPayloadRequest"}}}}}}}}
```


---

# 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-company-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.