# Welcome to MadKudu {% hint style="info" %} MadKudu was acquired by HG Insights in 2025. Please[ contact HG Insights](https://hginsights.com/contact-us/) or your account manager if you're interested in the MadKudu API. {% endhint %} On this site you'll find everything about MadKudu API and MCP. Shorthand: **MadAPI** and **MadMCP** ## Overview MadKudu is the customer & prospect intelligence layer for your GTM. It surfaces the signals your sales, marketing, and ops teams rely on. With MadKudu API and MCP, you can embed those insights directly into your tools, agents, and workflows.
## Why use MadKudu API and MCP 🔌 **Plug into your stack**\ Surface contact & account signals, scores and briefs programmatically - where ever your teams need them. 🧠 **Feed your AI agents**\ Give GPT copilots or internal tools the context they need to prioritize accounts, draft outreach, or prep for meetings. 🤝 **Build with confidence**\ Every endpoint is authenticated, logged, and monitored. We built this for enterprise-grade scale and security. ## What is the difference between API and MCP MCP is a new protocol to connect to AI tools like ChatGPT, Claude, Cursor, Dust, or your own GPT agents. * Your AI agent sends a natural language query like: *“Give me a brief about Walmart"* * The **MCP server translates** that into API calls to MadKudu * We send back structured responses the AI can use to take action or reply In short, the MCP is just a AI-tool-friendly way to interact with the API. ## When to use API and MCP **API Integration** Perfect for developers or systems that want to call specific endpoints (like "get account info") using standard REST calls. * You authenticate with API credentials * You get a structured JSON response from your request to the API endpoint **MCP (Model Context Protocol) Integration** Perfect for AI Agents and users of AI tools like ChatGPT, Claude, Cursor, Dust, or your own GPT agents. ### Jump right in
Getting Started Get your API Key/files/2uAgQO6fv9vcG1a7nA8x/pages/CyH2xJQs9yWJ1S8BYNav
Install MadKudu MCPPlug into your Claude, Cursor and other AI tools/files/x4gSastHkoV4tYoGafiA/pages/0lWAV7SmeHSAfTfDGjRJ/pages/0lWAV7SmeHSAfTfDGjRJ
If you're having any trouble using this API, shoot us an email at # Getting your API Key Get your API key to use MadKudu MCP or authenticate to MadKudu API
{% hint style="warning" %} Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. {% endhint %} ## Pre-requisite * You have an active MadKudu account * You are a MadKudu Admin ## How to create API keys {% hint style="info" %} Your API keys are personal, they are tied to your user and your permissions. You can create different ones for different integrations. {% endhint %} 1. Log into MadKudu admin console: [https://admin.madkudu.com](https://admin.madkudu.com/org/3327) 2. On the left navigation bar, go to **Personal Settings** then **My API Keys** 3. Click **Create API key**
4. Give it a name after the integration or tool you’ll use it with (e.g. "Cursor", "Zapier", "Claude"...) 5. Once created, you can copy you key:
## View your API keys 1. Log into MadKudu admin console: [https://admin.madkudu.com](https://admin.madkudu.com/org/3327) 2. On the left navigation bar, go to **Personal Settings** then **My API Keys** 3. You can see the list of all your API keys, and copy them
## How to Use the API Key ### with MadKudu MCP You'll use the API key when installing MadKudu MCP in your AI tools. Please[ follow instructions here](/madkudu-mcp/what-is-madkudu-mcp) ### with MadKudu API The MadKudu API uses API keys to authenticate requests. All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. The API Key must be passed in the `X-API-Key` header for **every requests**. API requests without authentication will also fail. # When to use API vs MCP In short * using the API is for human developers who need to integrate MadKudu with a service * using the MCP is for LLMs and AI Agents ## What is the difference between API and MCP MCP is a new protocol to connect to AI tools like ChatGPT, Claude, Cursor, Dust, or your own GPT agents. * Your AI agent sends a natural language query like: *“Give me a brief about Walmart"* * The **MCP server translates** that into API calls to MadKudu * We send back structured responses the AI can use to take action or reply In short, the MCP is just a AI-tool-friendly way to interact with the API. ## When to use API and MCP **API Integration** Perfect for developers or systems that want to call specific endpoints (like "get account info") using standard REST calls. * You authenticate with API credentials * You get a structured JSON response from your request to the API endpoint **MCP (Model Context Protocol) Integration** Perfect for AI Agents and users of AI tools like ChatGPT, Claude, Cursor, Dust, or your own GPT agents. # Usage and credits MadKudu’s API is billed using credits, a transparent system that makes it easy to track and manage your usage as your team scales. A credit is our universal pricing unit. Every API call consumes a number of credits based on the data it delivers and the cost we incur to produce it. ## How many credits does each endpoint use | Category | Example Endpoints | Credits | | ------------------------ | --------------------------------- | -------------------------------------------- | | Lookup | `POST /lookup/accounts` | 1 | | Detailed Info | `GET /accounts/{id}` | 3 | | Search (10 results) | `POST /search/accounts` | 1 | | Enrichment (20 postings) | `POST /enrichment/job-postings` | 3 | | Sourcing | `POST /sourcing/persons/discover` | **0** (as it consumes your provider credits) | | AI Web Search | `POST /ai/web-search` | 5 | | Organisation | `/organization` | 0 | | Ingestion Upload | `/ingestion/*` | 0 | ## How to monitor usage * Log into[ MadKudu Admin console ](https://admin.madkudu.com/) > **Settings** > **API Usage** to view the number of credits consumes and your remaining credit balance ## What’s included in my plan With the API access add-on you get a credit allowance. If you need more credits talk to your CSM. ## Real world examples | Use-case | Calls | Credits | | ---------------------------------------------- | -------------- | ---------------------------------- | | Enrich 1 000 new sign-ups (lookup) | 1 000 × 1 | **1 000** | | Pull detailed profiles for 100 target accounts | 100 × 2 | **200** | | Discover 500 net-new prospects | 20 batches × 5 |

100

| ## FAQ **Do unused credits roll over?**\ Yes **What happens if I hit my limit?**\ API responses return `429` with a “credits exhausted” message. # Your API Usage Monitor your API usage ## How to monitor your API usage You can track how many API calls your team is making directly in the[ MadKudu Admin console ](https://admin.madkudu.com/) > **Settings** > **API Usage** You can track the usage by API key and endpoints > 💡 **Note:** API calls made via **MCP tools** (e.g. AI agents, workflows) also count toward your usage. ## What’s included in my plan If your workspace has the **API Access add-on**, it includes a monthly allowance of API calls. > Need more volume?\ > → Reach out to your CSM to discuss increasing your limit or upgrading your plan. # What is MadKudu MCP Use MadKudu insights inside your favorite AI tools
MadKudu MCP (Model Context Protocol) is how you plug MadKudu intelligence into your own tools - whether it’s an AI agent, a prospecting assistant, a custom dashboard, or a RevOps automation, when they support MCP so you don't have to go through API connections ## Why using MadKudu MCP **For RevOps / Developers** MadKudu MCP bridges the gap between your data and your AI agents. If you are building internal agents, Sales Copilot or other assistants, use MadKudu MCP to give them the context of your prospects data, without messing around with APIs and ETLs. **For** **Sellers and non-technical folks** MadKudu MCP allows you to access all your prospects information directly from your favorite AI tools (Claude, chatGPT, etc.) in just a prompt. When connected, your AI tool can research in your own customer data and signals MadKudu has aggregated. Just like that, with just a prompt! ## What can you do with MadKudu MCP With MadKudu MCP connected, your AI agents can: * Research an account or person getting a full profile and brief * Source new people to engage with * Personalize outreach based on all signals found for these contacts * Trigger actions like adding a person to a sequence or drafting an email MadKudu MCP currently works with Claude, Cursor, Windsurf, and any MCP client that supports Streaming HTTP or STDIO transport # MadKudu MCP Playground MadKudu MCP Playground is your sandbox to explore how AI agents can natively interact with MadKudu’s Public API via Model Context Protocol (MCP). Whether you're testing automations, building AI sales assistants, or evaluating integration workflows, this playground gives you live access to MadKudu API capabilities packaged into reusable MCP tools. :point\_right: ### 🔍 What is this? The Playground is a web-based environment where you can experience * running a chatGPT prompt powered by **MadKudu MCP** * creating and running an agent * testing MadKudu MCP tools available This allows you to get a sneak peak at what’s possible with MadKudu + agents, without writing code or installing on your tools yet. # First time using MCP You don’t need to write code. Once you've [connected MadKudu in a couple clicks](/madkudu-mcp/install-in-ai-platforms-in-2min), in your tool just try asking: > Tell me who Francis at MadKudu is ## Use case examples * Prep for a sales meeting * Prospect into a new account * Source new contacts to go after * Personalize outreach ## Prompts examples > "Get me an account brief for Acme" > Who are the top users at Acme and what have they been doing? > "Find contacts at Acme in Marketing with Director or VP titles" > "Draft a personalized email to John at Acme using MadKudu details" # Install in AI platforms in 2min Integrate MadKudu to your AI Agents and platforms We support two ways to install MadKudu MCP {% hint style="info" %} For any installation, you'll need your API key. Refer to [this article](/getting-started/quickstart) to get your API key. {% endhint %} ## **Remote** - **Recommended for most users** No setup required—just plug in the URL, fastest way to get started For tools supporting MCP urls (Streamable HTTP transport) like Cursor, ChatGPT, use > This transport is now the standard way defined by the [MCP Protocol](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) ```bash https://mcp.madkudu.com/YOUR_API_KEY/mcp ``` For tools not supporting Streamable HTTP transport yet like Claude, Windsurf, use ```bash https://mcp.madkudu.com/YOUR_API_KEY/sse ``` See instructions for * [**Claude**](/madkudu-mcp/install-in-ai-platforms-in-2min/claude-anthropic) * [**ChatGPT**](/madkudu-mcp/install-in-ai-platforms-in-2min/chatgpt-openai) * [**Cursor**](/madkudu-mcp/install-in-ai-platforms-in-2min/cursor) * [**Dust**](/madkudu-mcp/install-in-ai-platforms-in-2min/dust) * [**Relevance AI**](/madkudu-mcp/install-in-ai-platforms-in-2min/relevance-ai) * [**Windsurf**](/madkudu-mcp/install-in-ai-platforms-in-2min/windsurf) ## **Local install** - **For custom agents and advanced users** * Run the MCP client locally (via `npx`) * Ideal for devs building internal copilots or CLI tools To use MadKudu MCP with STDIO transport, add the following JSON in the MCP configuration of your client: ```json { "command": "npx", "args": [ "-y", "supergateway", "--sse", "https://mcp.madkudu.com/YOUR_API_KEY/sse" ] } ``` # Claude (Anthropic) Connect MadKudu to your Claude [**Claude**](https://claude.ai/) is an AI assistant developed by Anthropic, designed for helpful, honest, and harmless conversations.\ Teams use Claude to build copilots, agents, and automation layers — and with MadKudu integrated, those agents can reason with your prospect data, personalize responses, and prioritize accounts more intelligently with the context they need. ## Pre-requisite You'll need your API key. Refer to [this article](/getting-started/quickstart) to get your API key. ## You are on a Claude Paid plan 1. Go to your [Claude Integrations settings](https://claude.ai/settings/integrations) and follow the official [Claude documentation](https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp) to add MadKudu as a custom integration. 2. Use the following remote MCP server URL (don't forget to replace the API key): ``` https://mcp.madkudu.com/YOUR_API_KEY/sse ``` :warning: Even though Claude complains about an authentication error, the MCP will work properly. 3. Verify Integration by asking Claude: "What tools do you have available from MadKudu?" You can now use MadKudu MCP in Claude Web, Desktop, Mobile Web. ## You are on a Claude Free plan You can use MadKudu MCP only in Claude Desktop. 1. **Download** [**MCPs for Humans**](https://mcpsforhumans.com/download) (it will allow you to install MadKudu as easily as you had a Claude paid plan, no code or black magic required) 2. Once installed, **open MCPs for Humans** from your apps 3. Click **Add a MCP Server** and select **MadKudu** 4. Enter your MadKudu API key (Refer to [this article](/getting-started/quickstart) to get your API key. ) 5. Click **Add Server**
6. Close MCPs for Humans, and **restart** your Claude Desktop (quit and reopen) :warning: Even though Claude shows you an error, the MCP should work properly. (Claude is just grumpy these days) In a new Claude chat, you should now see MadKudu in the tool list. Try a prompt like "Get account details about Walmart"
# Cursor Connect MadKudu to your Cursor [**Cursor**](https://cursor.ai/) is an AI-powered code editor that helps technical teams build faster by integrating with tools like GitHub, APIs, and docs.\ With MadKudu connected, developers and RevOps engineers can prototype workflows, automate research, and interact with GTM signals directly inside their coding environment. ## Pre-requisite You'll need your API key. Refer to [this article](/getting-started/quickstart) to get your API key. ## Add MadKudu MCP to Cursor 1. Click on the button below, it will take you to Cursor. Add to Cursor 2. Replace the URL making sure to replace your API key in the URL
3. Click **Install** You should now see MadMCP enabled
For more information, please follow the official [Cursor documentation](https://docs.cursor.com/context/model-context-protocol) ## **Enable Auto-Run Mode (Optional)** The auto-run mode allows the MCP tools to execute automatically without you having to confirm each step all the time 1. Navigate to Cursor Settings > Features > Chat 2. Toggle ON the **Auto-Run mode** ## **Verify the Integration** Open chat and ask "Get account details about Walmart" # ChatGPT (OpenAI) Coming Soon # Dust Connect MadKudu to your Windsurf [**Dust**](https://dust.tt/) is a platform to build, deploy, and run AI agents that connect to your internal tools and data sources.\ It’s especially useful for teams building AI copilots for sales, support, or operations — letting you combine LLMs with APIs, knowledge bases, and business context. ## Pre-requisite * You have a MadKudu API key. Refer to [this article](/getting-started/quickstart) to get your API key. * You are a Dust admin. ## Add MadKudu MCP as a Connection to your space 1. Go to **Spaces > Tools**, click **+ Add Tools,** then **+ Add MCP Server**
2. Enter the **URL** below **-** Don't forget to replace the API key in the URL. ```bash https://mcp.madkudu.com/YOUR_API_KEY/mcp ``` No need for a Bearer token
3. Click **Save** You'll now see the different tools available in the right panel Follow the official[ Dust documentation ](https://docs.dust.tt/docs/managing-datasources)for more information # Make Connect MadKudu to Make [**Make**](https://www.make.com/en) is a visual automation and AI Agent platform that lets teams build workflows and agents — without writing code.\ It’s especially useful for integrating MadKudu with other tools in your stack, enriching data flows, and running agents based on MadKudu Intelligence. ## Pre-requisite * You have a MadKudu API key. Refer to [this article](/getting-started/quickstart) to get your API key. * You are a Make admin. ## Add MadKudu MCP as a Connection in a Make Scenario 1. Log into your **Make** account, go to **Scenarios** (yes Scenarios, not Connections, trust me) 2. Click **+ Create a new Scenario** 3. Click on the module and search **MCP Client** and click on Call Tool 4. Click **+ Create a Connection** 5. Name it **MadKudu MCP** and in the MCP Server drop down select **+ New MCP Server**
6. In the **URL**, enter this URL replacing {YOUR\_MADKUDU\_API\_KEY} with your MadKudu API key ``` https://mcp.madkudu.com/{YOUR_MADKUDU_API_KEY}/mcp ``` 7. Click **Save** The connection is now made and you can see the list of available tools from MadKudu to use. In the **Connections** section of Make you'll find the MadKudu MCP connection you can change at any time # n8n Connect MadKudu to n8n [**n8n**](https://n8n.io/) is an open-source workflow automation platform that lets you connect services, trigger actions, and build logic using a visual interface. \ You can use it to integrate MadKudu into custom workflows — like enriching leads, scoring accounts, or syncing insights across your stack, prepping meeting.... If you are new to n8n, find below in this article an example of workflow ## To Add MadKudu MCP Tools to any workflow #### Pre-requisite * You have a MadKudu API key. Refer to [this article](/getting-started/quickstart) to get your API key. * You are a n8n admin 1. Log into **n8n** (local or Cloud) 2. In a project create an AI agent 3. For **Tool**, add **MCP Client Tool** 1. in **Parameters:** 1. **SSE Endpoint:** enter the following URL replacing your API key 2. **Authenticaiton**: None 3. **Tools**: All `https://mcp.madkudu.com/{YOUR_MADKUDU_API_KEY}/sse` /!\ note that the end of the url is `/sse` and not `/mcp` like you may have used in other tools ## Create your first workflow powered by MadKudu in n8n Let's create a simple agent on n8n that researches external meeting attendees, powered by MadKudu intelligence ### Pre-requisites You'll need * Generate an API for Google Calendar in your Google Console * An OpenAI API key, or other supported LLM * Your MadKudu API Key This is the flow you'll import
1. Download this JSON file that is the template of the workflow {% file src="/files/oRdQ667p1tBQkZuqFyKx" %} 1. Log into n8n (cloud or local) 2. Create a new Workflow (click **+** then **Worfklow**) 3. On the top right corner click **Import from File..** and import the JSON file you downloaded in 1.
5. Edit each node to connect to your Calendar, OpenAI and MadKudu MCP 1. Node Google Calendar: follow n8n docs to connect your Google account 2. Node "Keep Meeting with external attendees" change "@example.com" into "@yourdomain.com" with your company domain to filter out internal meetings 3. Node AI Agent 1. Add your OpenAI API key 2. In the Ai Agent prompt replace "example.com" with "yourdomain.com" with your company domain to filter out internal attendees 3. in the MCP tool, enter this URL replacing your MadKudu API key and removing the { } : `https://mcp.madkudu.com/{YOUR_MADKUDU_API_KEY}/sse` 6. Test your workflow ! # Relevance AI Connect MadKudu to Relevance AI [**Relevance AI**](https://relevanceai.com/) is a no-code platform for building LLM-powered agents that take action on your business data.\ It’s ideal for teams creating intelligent workflows — like research agents, enrichment bots, or SDR copilots that use MadKudu data to personalize outreach and prioritize leads. Relevance AI does not support connecting MCPs for other tools like MadKudu MCP today. You'll need to import individual Tools in Relevance AI that use MadKudu API. It's very easy just follow these steps. ## Pre-requisites * You are an admin in MadKudu * You are an admin in Relevance AI ## Step 1: Generate an API Key in MadKudu Follow[ instructions here](/getting-started/quickstart) to generate a MadKudu API key, name the key "**Relevance AI**" to track usage for this integration. Copy the key, you'll paste it at Step 2. ## Step 2: Save your MadKudu API Key in Relevance AI 1. Log into your Relevance AI account 2. Navigate to **Integrations & API Keys** on the left navigation bar 3. Click **Custom API Key,** on the right panel click **+Add Custom API Key** 4. Enter "**MadKudu"** as Key name - Make sure to use this exact name to be able to import directly the Tools listed at Step 3, otherwise you'll need to edit them 5. Paste your MadKudu API Key 6. Click **Save** Your MadKudu API Key is now saved for your workspace ## Step 3: Install MadKudu tools No need to create them from scratch, just import the following tools in your Relevance AI workspace by cloning them. Please note that you cannot use the tool directly in the UI, you need to clone them first.
Open the tools below and click on **Clone** at the top right. * [MadKudu: Get Person detailed info from email](https://app.relevanceai.com/notebook/bcbe5a/7e235fe879e7-49f2-ad54-4b71a047c3c3/e3756a62-a468-4cf2-9eb0-a3008257d3de) * [MadKudu: Get Account detailed info from domain](https://app.relevanceai.com/notebook/bcbe5a/7e235fe879e7-49f2-ad54-4b71a047c3c3/d24891f3-bb17-43dd-886f-a7099c13ca02) * [MadKudu: Get Account Most Active People](https://app.relevanceai.com/notebook/bcbe5a/7e235fe879e7-49f2-ad54-4b71a047c3c3/5291016f-5f6d-4bb3-9bf4-bbcc4914c6ba) * MadKudu: Get Person Activities * [MadKudu: Get Account Activities](https://app.relevanceai.com/notebook/bcbe5a/7e235fe879e7-49f2-ad54-4b71a047c3c3/31894f90-6426-4d5d-be78-c96ac192f269) * MadKudu: Get Account Deep Web Search * MadKudu: Get Account Brief instructions * more coming soon # Windsurf Connect MadKudu to your Windsurf [Windsurf](https://windsurf.com/) (formerly Codeium) is an AI-native IDE that helps developers build faster with smart autocompletion, context-aware agents, and in-editor previews.\ With MadKudu integrated, technical teams can fetch account insights, enrich leads, or automate sales workflows—directly from their code editor, using agents that connect to MadKudu intelligence. ## Pre-requisite You'll need your API key. Refer to [this article](/getting-started/quickstart) to get your API key. ### Add MadKudu MCP to Windsurf 1. Navigate to Windsurf > Settings > Windsurf Settings and go to Cascade tab 2. Click **Manage plugins** then **View raw config** 3. Add the following JSON to the MCP configuration: ```json { "mcpServers": { ... OTHER MCP SERVERS --- ADD THIS PART, DON'T FORGET TO REPLACE THE API KEY --- "MadMCP": { "serverUrl": "https://mcp.madkudu.com/YOUR_API_KEY/sse", "disabled": false } } } ``` 4. Save the file 5. Go back to manage plugins and click **Refresh** You should now see the MadMCP tools ## **Enable Turbo Mode (Optional)** The Turbo mode allows the MCP tools to execute automatically without you having to confirm each step all the time Refer to the [official Windsurf documentation](https://docs.windsurf.com/windsurf/terminal#turbo-mode) to turn it ont ## **Verify the Integration** Open a Cascade chat and ask "Get account details about Walmart" For more information please follow the official[ Windsurf documentation](https://docs.windsurf.com/windsurf/cascade/mcp) # Zapier New MadKudu Actions available in Zapier - Coming soon! # MadMCP tools Tools available in your AI platform when integrating MadKudu MCP
EntityTool NameDescription
Accountmadkudu-account-detailsReturns enriched account information including firmographics, scoring, social handles and engagement stats
Accountmadkudu-account-activitiesGet all activities associated with an account
Accountmadkudu-account-top-usersLists the top users from the account based on activity volume. Useful for identifying champions or active contacts.
Accountmadkudu-search-accountsSearch for accounts existing in MadKudu (your known contacts from all your integrations connected to MadKudu)
Accountmadkudu-account-news-deep-searchSearch for relevant news online about an account
Accountmadkudu-account-brief-instructionsProvides instructions as a structured prompt to generate a sales account briefs calling other MadMCP tools
Personmadkudu-person-activitiesGet all activities associated with a person
Personmadkudu-person-detailsReturns enriched contact information including title, persona, email, LinkedIn, scoring, company and engagement stats
Personmadkudu-discover-personsFinds new prospects not in your CRM based on title, seniority and company
Personmadkudu-enrich-personsFinds contact details like email and phone numbers for people discovered
Personmadkudu-search-personsSearch for persons existing in MadKudu (your known contacts from all your integrations connected to MadKudu)
Organizationmadkudu-value-propGet the value prop for your company to provide context when generating an account brief or personalizing email
Not seeing a tool you need? Send feedback to ! # Building AI Agents powered by MadKudu
## 🤖 What is an AI Agent? An **AI agent** is an automation with AI in it. In practice, this means there is one or more parts of it where an LLM **makes a decision** on its own instead of having only determinist "IF this THEN that" as rules. AI agents introduce a level of **autonomy and reasoning.** They can act on ambiguous instructions (e.g. “find the best contacts to reach out to”) and pulling in data from various systems (like MadKudu) to make decisions. > Example: an AI agent drafting emails decide on its own what to write in this email. While a non-AI workflow would use a template text with placeholders and the email would look similar for all recipients. AI agents are not products—they are **custom-built automations**. And like any automation, when something goes wrong, it’s important to trace which part of the system is responsible ## 🧱 The 4 Components of Any AI Agent To build a working AI agent using MadKudu data, you need **three components**: ### **1. The Orchestration Platform** This is **where the agent logic lives and gets executed.** It’s the engine that chains steps together. Example: n8n, Make, Zapier, Dust, custom code running in Cursor ... \ These platforms execute the flow: pulling data, making decisions, sending messages, etc. ### **2. The LLM** This is the **“thinking” layer** of your agent. You can use: OpenAI, Claude, Mistral models, any model you want ### **3. The Prompt** The prompt contains the instructions in plain english that will be interpreted by the LLM Example: * "Find contacts at {company}" * "Draft an email for {email} using all the information you know from MadKudu" {% hint style="warning" %} LLMs are powerful but inherently unpredictable. They can hallucinate, misinterpret instructions, or fail entirely when given poorly structured inputs. When building agents, much of the effort goes into **refining prompts** and **selecting the right model** to minimize the risk of misinterpretation and ensure more consistent and reliable outputs. {% endhint %} ### **4. The Data layer: MadKudu MCP** MadKudu provides the **data layer**—the context that inform the agent’s decisions. Through the MadKudu Public API and MCP integration, you can * get information about your accounts and contacts: firmographics, demographics, scores, engagement activities with your website, product, marketing, job history... * search for accounts and contacts * source and enrich net new contacts ## 🧪 Example Use Case: Meeting Prep Agent Here’s how a MadKudu-powered AI agent for meeting prep might be built: * **Orchestration**: n8n monitors your calendar, detects meetings with prospects. * **LLM**: GPT-4 summarizes MadKudu data and past emails into a briefing doc. * **MadKudu**: The MCP provides the account brief, top users, recent activity, and firmographics. You decide when the agent runs, what it generates, and where it shows up (Notion, Slack, Google Docs…). {% hint style="success" %} MadKudu helps power your AI agents by exposing real-time GTM data through secure APIs and the Model Context Protocol (MCP). But we don’t control: * Which tool you use to orchestrate * How you write your prompts * How your model interprets the data Treat MadKudu as your **intelligent data layer**—not the AI agent itself. {% endhint %} # AI Agent Templates {% embed url="" %} ## n8n Templates In a new workflow, Import the template to your n8n instance and edit each nodes to connect your accounts. {% hint style="success" %} Using another integration (CRM, Calendar or Sales Engagement platform...) than the one in the templates? Import them as inspiration and adap them!
Feel free to ask for help at {% endhint %} ## Meeting Prep Just click on the template (official in n8n library) to open it and click "**Use for free" to import it** 👉 [**https://n8n.io/workflows/6752-generate-ai-meeting-briefs-for-google-calendar-with-gpt-4-and-madkudu-mcp/**](https://n8n.io/workflows/6752-generate-ai-meeting-briefs-for-google-calendar-with-gpt-4-and-madkudu-mcp/) {% embed url="" %}
## Generate Account Brief in Outreach Just click on the template (official in n8n library) to open it and click "**Use for free" to import it** :point\_right:
## Generate and sync personalized email to Outreach {% file src="/files/gVdLJLtyRjJk39OedNBt" %}
## Monitor specific news sources and send to MadKudu coming soon ## Cursor rule Templates
🔧 Personalized Outreach Generator to customer **Context** You are a customer-facing rep at Acme reaching out to an executive at an existing customer. You have likely not interacted with this person before.\ The goal is to prepare a markdown file with an outreach plan and drafted messaging. Please make sure to create a **markdown document** with the output at the end of the process. #### Research Start by completing ALL the required research steps below to find the 5 most interesting angles to use to reach out to them: * **Account Details**: Includes company insights (e.g., hiring, partnerships, technology stack, sales motion, risk). Use `madkudu-account-details` to understand company use, top users, tech stack, and signals. * **Research Account**: Use `madkudu-account-research` to understand company context, news, and relevant insights. * **Top Users in the Account**: Use `madkudu-account-top-users` to find the top users from this person's account. It can be helpful to name drop top users especially if they are in the same part of the org. * **Contact Details**: Includes contact role, persona, email, and Salesforce ID. Use `madkudu-person-details` to understand the person's role, persona, and engagement. * **Contact Web Search**: Search the web for any relevant activity by this contact to understand what this person is interested in, what they care about... This can be very helpful to build some rapport. You can do this by searching "FirstName LastName Company". * **Contact Picture Web Search**: look for the person's linkedin profile picture, background picture, or other public pictures which might give a hint to their interests and provide us with a personal angle. Make sure to do all of these steps in the research. ### Instructions: 1. **Perform the thorough research** as described above. 2. **Find 5 angles** to justify reaching out based on how relevant they are to MadKudu + their company, their role, your shared personal interests, their personal interests... Stack rank them accordingly 3. **Extract contextual personalization** from the research for each of the 5 angles. 4. **Output an outreach document** in markdown format that covers for each angle the reason it was selected, a draft email sequence (3 emails), and a draft linkedin connection request message. Always generate a markdown document at the end of the process. ### Additional Information: #### MadKudu value prop: MadKudu turns fragmented go-to-market data into real-time, actionable intelligence for both human sellers and AI agents. By unifying and enriching signals across your GTM stack, it powers smarter prioritization, personalized outreach, and fully agentic workflows through a composable API layer. #### Guidelines: * **Avoid referencing specific activity counts** (e.g., don't say "you clicked 87 times"). * **Sound human and not creepy** — your purpose is to be helpful. * **Tone** professional, helpful, and neutral tone. Avoid using excessive praise, flattery, or overly enthusiastic language. * **Refer to engagement behaviors** (e.g., "you've been actively leveraging alerts") and connect them to their role's likely goals (e.g., efficiency, alignment, GTM execution). * **If lacking behavioral insight**, use company-level context (e.g., hiring, funding, GTM motion) to form a relevant angle. * **Always acknowledge existing context** from past email exchanges to maintain continuity in the conversation. * **Avoid sycophancy** to sound human, avoid sounding like a chatbot (e.g., NEVER say things like "I was impressed by your journey") #### Angles: Below is a stack rank of the most interesting angles to use when they are found. This is primarily for illustration purposes and is not an exhaustive: * Shared personal interest (e.g., fly fishing, sailing...) * Major company news (e.g., IPO, fundraise, new exec team...) * Product usage within their team (e.g., telling a VP of commercials sales that 10 of their commercial AEs are seeing success with the tool...)
# Authentication Learn how to authenticate to MadKudu API
The MadKudu API uses API keys to authenticate requests. Follow [this article ](/getting-started/quickstart)to get your API key. All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. The API Key must be passed in the `X-API-Key` header for **every requests**. API requests without authentication will also fail. # Lookup Find any account or person by the identifier you have (email, domain Linkedin handle, Twitter, salesforce ID, hubspot ID ...) and get their MadKudu ID.
Each endpoint accepts multiple types of identifiers as input, and returns MadKudu ID, social IDs, system IDs and enriched attributes, making it easy to build a robust identity graph across your systems. These endpoints are ideal for: * Resolving identities across tools and platforms * Getting the person/account ID for the[ Detailed Information ](/api/detailed-information)endpoints * Enriching your CRM or CDP with consistent person/account data ## Lookup account by identifiers > Lookup accounts in your database using domain names, social media handles, or CRM IDs. Returns company profile with contact details, firmographics, and customer fit scoring. Use it to get the MadKudu ID to fetch more information in the Detailed Information endpoints. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Lookup"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"AccountDetailsMini":{"type":"object","required":["mk_id","source_system","name","domain","socials","location"],"properties":{"mk_id":{"type":"string","description":"Unique identifier for the account in MadKudu"},"source_system":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SourceSystem"}],"description":"Source system information"},"name":{"type":"string","description":"Name of the account"},"domain":{"type":"string","description":"Domain of the account"},"logo":{"type":"string","description":"URL of the account's logo"},"description":{"type":"string","description":"Description of the account"},"industry":{"type":"string","description":"Industry the account operates in"},"founded_year":{"type":"integer","format":"int32","description":"Year the account was founded"},"raised_amount":{"type":"number","format":"double","description":"Total amount raised by the account"},"employees_count":{"type":"integer","format":"int32","description":"Number of employees in the account"},"active_users":{"type":"integer","format":"int32","description":"Number of active users"},"activities_count":{"type":"integer","format":"int32","description":"Number of activities"},"socials":{"allOf":[{"$ref":"#/components/schemas/Common.Models.AccountSocials"}],"description":"Social media handles"},"location":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Location"}],"description":"Location information"}}},"Common.Models.SourceSystem":{"type":"object","required":["id","system","object"],"properties":{"id":{"type":"string","description":"Unique identifier in the source system"},"system":{"type":"string","description":"Name of the source system"},"object":{"type":"string","description":"Object type in the source system"}}},"Common.Models.AccountSocials":{"type":"object","properties":{"linkedin_handle":{"type":"string","description":"LinkedIn company handle"},"twitter_handle":{"type":"string","description":"Twitter company handle"},"crunchbase_handle":{"type":"string","description":"Crunchbase organization handle"},"website":{"type":"string","description":"Company website URL"}}},"Common.Models.Location":{"type":"object","properties":{"country":{"type":"string","description":"Country"},"state":{"type":"string","description":"State or region"},"city":{"type":"string","description":"City"}}},"Common.Errors.ValidationError":{"type":"object","required":["detail"],"properties":{"detail":{"type":"array","items":{"type":"object","properties":{"loc":{"type":"array","prefixItems":[{"anyOf":[{"type":"string"},{"type":"integer","format":"int32"}]}],"description":"What part is invalid"},"msg":{"type":"string","description":"Message discribing the error"},"type":{"type":"string","description":"Type of the error"},"input":{},"ctx":{}},"required":["loc","msg","type"]}}},"description":"Error return when body sent is invalid"}}},"paths":{"/lookup/accounts":{"get":{"operationId":"Lookup_lookupAccounts","summary":"Lookup account by identifiers","description":"Lookup accounts in your database using domain names, social media handles, or CRM IDs. Returns company profile with contact details, firmographics, and customer fit scoring. Use it to get the MadKudu ID to fetch more information in the Detailed Information endpoints.","parameters":[{"name":"domain","in":"query","required":false,"description":"Company website domain (e.g., 'madkudu.com')","schema":{"type":"string"},"explode":false},{"name":"linkedin","in":"query","required":false,"description":"LinkedIn company page handle (e.g., 'company/madkudu')","schema":{"type":"string"},"explode":false},{"name":"twitter","in":"query","required":false,"description":"Twitter company handle","schema":{"type":"string"},"explode":false},{"name":"crunchbase","in":"query","required":false,"description":"Crunchbase company profile handle (e.g., 'organization/madkudu')","schema":{"type":"string"},"explode":false},{"name":"external_id","in":"query","required":false,"description":"Your CRM account ID (Salesforce, HubSpot, etc.)","schema":{"type":"string"},"explode":false}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AccountDetailsMini"}}}}},"422":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ValidationError"}}}}},"tags":["Lookup"]}}}} ``` ## Lookup person by identifiers > Lookup people in your database using email addresses, social media profiles, or CRM IDs. Returns contact profile with job details, company information, and lead scoring. Use it to get the MadKudu ID to fetch more information in the Detailed Information endpoints. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Lookup"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"PersonDetailsMini":{"type":"object","required":["mk_id","source_system","email","name","company","socials","location"],"properties":{"mk_id":{"type":"string","description":"Unique identifier for the person in MadKudu"},"source_system":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SourceSystem"}],"description":"Source system information"},"email":{"type":"string","description":"Email of the person"},"name":{"type":"string","description":"Full name of the person"},"first_name":{"type":"string","description":"First name of the person"},"last_name":{"type":"string","description":"Last name of the person"},"title":{"type":"string","description":"Title of the person"},"persona":{"type":"string","description":"Persona of the person"},"avatar":{"type":"string","description":"Avatar URL of the person"},"company":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CompanyReference"}],"description":"Company information"},"socials":{"allOf":[{"$ref":"#/components/schemas/Common.Models.PersonSocials"}],"description":"Social media handles"},"location":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Location"}],"description":"Location information"},"has_left_company":{"type":"boolean","description":"Whether the person has left the company"},"activities":{"description":"Activities information"}}},"Common.Models.SourceSystem":{"type":"object","required":["id","system","object"],"properties":{"id":{"type":"string","description":"Unique identifier in the source system"},"system":{"type":"string","description":"Name of the source system"},"object":{"type":"string","description":"Object type in the source system"}}},"Common.Models.CompanyReference":{"type":"object","required":["domain","mk_id"],"properties":{"domain":{"type":"string","description":"Domain of the company"},"mk_id":{"type":"string","description":"MadKudu ID of the company"}}},"Common.Models.PersonSocials":{"type":"object","properties":{"linkedin_handle":{"type":"string","description":"LinkedIn handle"},"twitter_handle":{"type":"string","description":"Twitter handle"},"crunchbase_handle":{"type":"string","description":"Crunchbase handle"},"website":{"type":"string","description":"Website URL"}}},"Common.Models.Location":{"type":"object","properties":{"country":{"type":"string","description":"Country"},"state":{"type":"string","description":"State or region"},"city":{"type":"string","description":"City"}}},"Common.Errors.ValidationError":{"type":"object","required":["detail"],"properties":{"detail":{"type":"array","items":{"type":"object","properties":{"loc":{"type":"array","prefixItems":[{"anyOf":[{"type":"string"},{"type":"integer","format":"int32"}]}],"description":"What part is invalid"},"msg":{"type":"string","description":"Message discribing the error"},"type":{"type":"string","description":"Type of the error"},"input":{},"ctx":{}},"required":["loc","msg","type"]}}},"description":"Error return when body sent is invalid"}}},"paths":{"/lookup/persons":{"get":{"operationId":"Lookup_lookupPersons","summary":"Lookup person by identifiers","description":"Lookup people in your database using email addresses, social media profiles, or CRM IDs. Returns contact profile with job details, company information, and lead scoring. Use it to get the MadKudu ID to fetch more information in the Detailed Information endpoints. ","parameters":[{"name":"email","in":"query","required":false,"description":"Person's email address","schema":{"type":"string"},"explode":false},{"name":"linkedin","in":"query","required":false,"description":"LinkedIn profile handle (e.g., 'in/francisbrero')","schema":{"type":"string"},"explode":false},{"name":"twitter","in":"query","required":false,"description":"Twitter profile handle","schema":{"type":"string"},"explode":false},{"name":"external_id","in":"query","required":false,"description":"Your CRM contact ID (Salesforce Lead/Contact, HubSpot Contact, etc.)","schema":{"type":"string"},"explode":false}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PersonDetailsMini"}}}}},"422":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ValidationError"}}}}},"tags":["Lookup"]}}}} ``` # Detailed Information Get the full picture on any person or account using the MadKudu ID
Use these endpoints to fetch rich context about a person or account using the MadKudu ID.\ Perfect for surfacing **firmographics, demographics, engagement metrics, and scores** in your tools or workflows ## Get Account By Id > Retrieve comprehensive account information including firmographics, customer fit scoring, activity metrics, and contact details. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Accounts"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Common.Models.AccountDetail":{"type":"object","required":["mk_id","source_system","name","domain","socials","location","scores","aggregations"],"properties":{"mk_id":{"type":"string","description":"Unique identifier for the account in MadKudu"},"source_system":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SourceSystem"}],"description":"Source system information"},"name":{"type":"string","description":"Account name"},"domain":{"type":"string","description":"Account domain"},"logo":{"type":"string","description":"Logo URL"},"description":{"type":"string","description":"Account description"},"industry":{"type":"string","description":"Industry"},"founded_year":{"type":"integer","format":"int32","description":"Founded year"},"raised_amount":{"type":"number","format":"double","description":"Raised amount"},"employees_count":{"type":"integer","format":"int32","description":"Number of employees"},"active_users":{"type":"integer","format":"int32","description":"Number of active users"},"activities_count":{"type":"integer","format":"int32","description":"Total activities count"},"socials":{"allOf":[{"$ref":"#/components/schemas/Common.Models.AccountSocials"}],"description":"Social media handles"},"location":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Location"}],"description":"Location information"},"scores":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Scores"}],"description":"Scoring information"},"aggregations":{"type":"object","unevaluatedProperties":{"$ref":"#/components/schemas/Common.Models.AggregationValue"},"description":"Aggregations data"}}},"Common.Models.SourceSystem":{"type":"object","required":["id","system","object"],"properties":{"id":{"type":"string","description":"Unique identifier in the source system"},"system":{"type":"string","description":"Name of the source system"},"object":{"type":"string","description":"Object type in the source system"}}},"Common.Models.AccountSocials":{"type":"object","properties":{"linkedin_handle":{"type":"string","description":"LinkedIn company handle"},"twitter_handle":{"type":"string","description":"Twitter company handle"},"crunchbase_handle":{"type":"string","description":"Crunchbase organization handle"},"website":{"type":"string","description":"Company website URL"}}},"Common.Models.Location":{"type":"object","properties":{"country":{"type":"string","description":"Country"},"state":{"type":"string","description":"State or region"},"city":{"type":"string","description":"City"}}},"Common.Models.Scores":{"type":"object","required":["customer_fit","likelihood_to_buy"],"properties":{"customer_fit":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CustomerFit"}],"description":"Customer fit information"},"likelihood_to_buy":{"allOf":[{"$ref":"#/components/schemas/Common.Models.LikelihoodToBuy"}],"description":"Likelihood to buy information"}}},"Common.Models.CustomerFit":{"type":"object","required":["score","segment"],"properties":{"score":{"type":"number","format":"double","description":"Customer fit score"},"segment":{"type":"string","description":"Customer fit segment"},"signals":{"type":"string","description":"Customer fit signals"}}},"Common.Models.LikelihoodToBuy":{"type":"object","required":["score","segment"],"properties":{"score":{"type":"number","format":"double","description":"Likelihood to buy score"},"segment":{"type":"string","description":"Likelihood to buy segment"}}},"Common.Models.AggregationValue":{"type":"object","required":["aggregation_name_display","aggregation_value"],"properties":{"aggregation_name_display":{"type":"string","description":"Display name for the aggregation"},"aggregation_value":{"type":"number","format":"double","description":"Aggregation value"}}}}},"paths":{"/accounts/{mk_id}":{"get":{"operationId":"Accounts_getAccount","summary":"Get Account By Id","description":"Retrieve comprehensive account information including firmographics, customer fit scoring, activity metrics, and contact details.","parameters":[{"name":"mk_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Models.AccountDetail"}}}}},"tags":["Accounts"]}}}} ``` ## Get Account Activities > Get activities associated with an account including website visits, email engagement, product usage, and sales touchpoints. Filter by activity type, date range, or specific team members. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Accounts"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Common.Models.AccountActivityResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Common.Models.AccountActivity"},"description":"Account activity data"},"meta":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Meta"}],"description":"Metadata"}}},"Common.Models.AccountActivity":{"type":"object","required":["person"],"properties":{"person":{"allOf":[{"$ref":"#/components/schemas/Common.Models.PersonDetail"}],"description":"Person who performed the activity"}},"allOf":[{"$ref":"#/components/schemas/Common.Models.ActivityBase"}]},"Common.Models.PersonDetail":{"type":"object","required":["mk_id","source_system","email","name","company","socials","location","scores","aggregations"],"properties":{"mk_id":{"type":"string","description":"Unique identifier for the person in MadKudu"},"source_system":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SourceSystem"}],"description":"Source system information"},"email":{"type":"string","description":"Email address"},"name":{"type":"string","description":"Full name"},"first_name":{"type":"string","description":"First name"},"last_name":{"type":"string","description":"Last name"},"title":{"type":"string","description":"Job title"},"persona":{"type":"string","description":"Persona"},"avatar":{"type":"string","description":"Avatar URL"},"company":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CompanyReference"}],"description":"Company information"},"socials":{"allOf":[{"$ref":"#/components/schemas/Common.Models.PersonSocials"}],"description":"Social media handles"},"location":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Location"}],"description":"Location information"},"has_left_company":{"type":"boolean","description":"Has left company"},"scores":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Scores"}],"description":"Scoring information"},"activities":{"description":"Activities information"},"aggregations":{"type":"object","unevaluatedProperties":{"$ref":"#/components/schemas/Common.Models.AggregationValue"},"description":"Aggregations data"}}},"Common.Models.SourceSystem":{"type":"object","required":["id","system","object"],"properties":{"id":{"type":"string","description":"Unique identifier in the source system"},"system":{"type":"string","description":"Name of the source system"},"object":{"type":"string","description":"Object type in the source system"}}},"Common.Models.CompanyReference":{"type":"object","required":["domain","mk_id"],"properties":{"domain":{"type":"string","description":"Domain of the company"},"mk_id":{"type":"string","description":"MadKudu ID of the company"}}},"Common.Models.PersonSocials":{"type":"object","properties":{"linkedin_handle":{"type":"string","description":"LinkedIn handle"},"twitter_handle":{"type":"string","description":"Twitter handle"},"crunchbase_handle":{"type":"string","description":"Crunchbase handle"},"website":{"type":"string","description":"Website URL"}}},"Common.Models.Location":{"type":"object","properties":{"country":{"type":"string","description":"Country"},"state":{"type":"string","description":"State or region"},"city":{"type":"string","description":"City"}}},"Common.Models.Scores":{"type":"object","required":["customer_fit","likelihood_to_buy"],"properties":{"customer_fit":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CustomerFit"}],"description":"Customer fit information"},"likelihood_to_buy":{"allOf":[{"$ref":"#/components/schemas/Common.Models.LikelihoodToBuy"}],"description":"Likelihood to buy information"}}},"Common.Models.CustomerFit":{"type":"object","required":["score","segment"],"properties":{"score":{"type":"number","format":"double","description":"Customer fit score"},"segment":{"type":"string","description":"Customer fit segment"},"signals":{"type":"string","description":"Customer fit signals"}}},"Common.Models.LikelihoodToBuy":{"type":"object","required":["score","segment"],"properties":{"score":{"type":"number","format":"double","description":"Likelihood to buy score"},"segment":{"type":"string","description":"Likelihood to buy segment"}}},"Common.Models.AggregationValue":{"type":"object","required":["aggregation_name_display","aggregation_value"],"properties":{"aggregation_name_display":{"type":"string","description":"Display name for the aggregation"},"aggregation_value":{"type":"number","format":"double","description":"Aggregation value"}}},"Common.Models.ActivityBase":{"type":"object","required":["event_id","event","event_display","event_timestamp","activity_type","account_id"],"properties":{"event_id":{"type":"string","description":"Event ID"},"event":{"type":"string","description":"Event name"},"event_display":{"type":"string","description":"Event display name"},"event_timestamp":{"type":"string","description":"Event timestamp"},"activity_type":{"type":"string","description":"Activity type"},"account_id":{"type":"string","description":"Account ID"}}},"Common.Models.Meta":{"type":"object","properties":{"limit":{"type":"integer","format":"int32","description":"Number of results returned"},"total":{"type":"integer","format":"int32","description":"Total number of results available"},"has_next_page":{"type":"boolean","description":"Whether there are more results"},"next_cursor":{"type":"integer","format":"int32","description":"Next cursor for pagination"}}},"Common.Models.AccountActivitySearchRequest":{"type":"object","properties":{"limit":{"type":"integer","format":"int32","description":"Number of results to return"},"cursor":{"type":"integer","format":"int32","description":"Cursor for pagination"},"search":{"type":"string","description":"Search query"},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Common.Models.AccountActivityFilter"},"description":"Filters to apply"},"filterLogic":{"type":"string","enum":["AND","OR"],"description":"Filter logic"},"sort":{"type":"array","items":{"$ref":"#/components/schemas/Common.Models.SortingParam"},"description":"Sorting parameters"}}},"Common.Models.AccountActivityFilter":{"type":"object","required":["property","operator","value"],"properties":{"property":{"allOf":[{"$ref":"#/components/schemas/Common.Models.AccountActivityFilterProperty"}],"description":"Property to filter by"},"operator":{"allOf":[{"$ref":"#/components/schemas/Common.Models.FilterOperator"}],"description":"Filter operator"},"value":{"anyOf":[{"type":"string"},{"type":"integer","format":"int32"},{"type":"number","format":"double"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}],"description":"Filter value"}}},"Common.Models.AccountActivityFilterProperty":{"type":"string","enum":["event","event_display","event_timestamp","activity_type","name","email","title"]},"Common.Models.FilterOperator":{"type":"string","enum":["IS","IS_NOT","GT","GTE","LT","LTE","IN","NOT_IN","BETWEEN","NOT_BETWEEN","LIKE","NOT_LIKE","IS_NULL","IS_NOT_NULL","CONTAINS","NOT_CONTAINS","STARTS_WITH","ENDS_WITH","IS_EMPTY","IS_NOT_EMPTY"]},"Common.Models.SortingParam":{"type":"object","required":["sort_by","sort_order"],"properties":{"sort_by":{"type":"string","description":"Field to sort by"},"sort_order":{"type":"string","enum":["asc","desc"],"description":"Sort order"}}}}},"paths":{"/accounts/{mk_id}/activities":{"post":{"operationId":"Accounts_getAccountActivities","summary":"Get Account Activities","description":"Get activities associated with an account including website visits, email engagement, product usage, and sales touchpoints. Filter by activity type, date range, or specific team members.","parameters":[{"name":"mk_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Models.AccountActivityResponse"}}}}},"tags":["Accounts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Models.AccountActivitySearchRequest"}}}}}}}} ``` ## Get Account Top Persons > Fetch the most engaged contacts at a company, ranked by activity level and seniority. Helps identify champions, decision makers, and active stakeholders for targeted outreach and relationship building. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Accounts"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Common.Models.PersonDetail":{"type":"object","required":["mk_id","source_system","email","name","company","socials","location","scores","aggregations"],"properties":{"mk_id":{"type":"string","description":"Unique identifier for the person in MadKudu"},"source_system":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SourceSystem"}],"description":"Source system information"},"email":{"type":"string","description":"Email address"},"name":{"type":"string","description":"Full name"},"first_name":{"type":"string","description":"First name"},"last_name":{"type":"string","description":"Last name"},"title":{"type":"string","description":"Job title"},"persona":{"type":"string","description":"Persona"},"avatar":{"type":"string","description":"Avatar URL"},"company":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CompanyReference"}],"description":"Company information"},"socials":{"allOf":[{"$ref":"#/components/schemas/Common.Models.PersonSocials"}],"description":"Social media handles"},"location":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Location"}],"description":"Location information"},"has_left_company":{"type":"boolean","description":"Has left company"},"scores":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Scores"}],"description":"Scoring information"},"activities":{"description":"Activities information"},"aggregations":{"type":"object","unevaluatedProperties":{"$ref":"#/components/schemas/Common.Models.AggregationValue"},"description":"Aggregations data"}}},"Common.Models.SourceSystem":{"type":"object","required":["id","system","object"],"properties":{"id":{"type":"string","description":"Unique identifier in the source system"},"system":{"type":"string","description":"Name of the source system"},"object":{"type":"string","description":"Object type in the source system"}}},"Common.Models.CompanyReference":{"type":"object","required":["domain","mk_id"],"properties":{"domain":{"type":"string","description":"Domain of the company"},"mk_id":{"type":"string","description":"MadKudu ID of the company"}}},"Common.Models.PersonSocials":{"type":"object","properties":{"linkedin_handle":{"type":"string","description":"LinkedIn handle"},"twitter_handle":{"type":"string","description":"Twitter handle"},"crunchbase_handle":{"type":"string","description":"Crunchbase handle"},"website":{"type":"string","description":"Website URL"}}},"Common.Models.Location":{"type":"object","properties":{"country":{"type":"string","description":"Country"},"state":{"type":"string","description":"State or region"},"city":{"type":"string","description":"City"}}},"Common.Models.Scores":{"type":"object","required":["customer_fit","likelihood_to_buy"],"properties":{"customer_fit":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CustomerFit"}],"description":"Customer fit information"},"likelihood_to_buy":{"allOf":[{"$ref":"#/components/schemas/Common.Models.LikelihoodToBuy"}],"description":"Likelihood to buy information"}}},"Common.Models.CustomerFit":{"type":"object","required":["score","segment"],"properties":{"score":{"type":"number","format":"double","description":"Customer fit score"},"segment":{"type":"string","description":"Customer fit segment"},"signals":{"type":"string","description":"Customer fit signals"}}},"Common.Models.LikelihoodToBuy":{"type":"object","required":["score","segment"],"properties":{"score":{"type":"number","format":"double","description":"Likelihood to buy score"},"segment":{"type":"string","description":"Likelihood to buy segment"}}},"Common.Models.AggregationValue":{"type":"object","required":["aggregation_name_display","aggregation_value"],"properties":{"aggregation_name_display":{"type":"string","description":"Display name for the aggregation"},"aggregation_value":{"type":"number","format":"double","description":"Aggregation value"}}}}},"paths":{"/accounts/{mk_id}/top-persons":{"get":{"operationId":"Accounts_getAccountTopPersons","summary":"Get Account Top Persons","description":"Fetch the most engaged contacts at a company, ranked by activity level and seniority. Helps identify champions, decision makers, and active stakeholders for targeted outreach and relationship building.","parameters":[{"name":"mk_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32"},"explode":false}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Common.Models.PersonDetail"}}}}}},"tags":["Accounts"]}}}} ``` ## Get Person By Id > Retrieve comprehensive person information including job details, company background, engagement scoring, and activity metrics. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Persons"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Common.Models.PersonDetail":{"type":"object","required":["mk_id","source_system","email","name","company","socials","location","scores","aggregations"],"properties":{"mk_id":{"type":"string","description":"Unique identifier for the person in MadKudu"},"source_system":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SourceSystem"}],"description":"Source system information"},"email":{"type":"string","description":"Email address"},"name":{"type":"string","description":"Full name"},"first_name":{"type":"string","description":"First name"},"last_name":{"type":"string","description":"Last name"},"title":{"type":"string","description":"Job title"},"persona":{"type":"string","description":"Persona"},"avatar":{"type":"string","description":"Avatar URL"},"company":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CompanyReference"}],"description":"Company information"},"socials":{"allOf":[{"$ref":"#/components/schemas/Common.Models.PersonSocials"}],"description":"Social media handles"},"location":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Location"}],"description":"Location information"},"has_left_company":{"type":"boolean","description":"Has left company"},"scores":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Scores"}],"description":"Scoring information"},"activities":{"description":"Activities information"},"aggregations":{"type":"object","unevaluatedProperties":{"$ref":"#/components/schemas/Common.Models.AggregationValue"},"description":"Aggregations data"}}},"Common.Models.SourceSystem":{"type":"object","required":["id","system","object"],"properties":{"id":{"type":"string","description":"Unique identifier in the source system"},"system":{"type":"string","description":"Name of the source system"},"object":{"type":"string","description":"Object type in the source system"}}},"Common.Models.CompanyReference":{"type":"object","required":["domain","mk_id"],"properties":{"domain":{"type":"string","description":"Domain of the company"},"mk_id":{"type":"string","description":"MadKudu ID of the company"}}},"Common.Models.PersonSocials":{"type":"object","properties":{"linkedin_handle":{"type":"string","description":"LinkedIn handle"},"twitter_handle":{"type":"string","description":"Twitter handle"},"crunchbase_handle":{"type":"string","description":"Crunchbase handle"},"website":{"type":"string","description":"Website URL"}}},"Common.Models.Location":{"type":"object","properties":{"country":{"type":"string","description":"Country"},"state":{"type":"string","description":"State or region"},"city":{"type":"string","description":"City"}}},"Common.Models.Scores":{"type":"object","required":["customer_fit","likelihood_to_buy"],"properties":{"customer_fit":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CustomerFit"}],"description":"Customer fit information"},"likelihood_to_buy":{"allOf":[{"$ref":"#/components/schemas/Common.Models.LikelihoodToBuy"}],"description":"Likelihood to buy information"}}},"Common.Models.CustomerFit":{"type":"object","required":["score","segment"],"properties":{"score":{"type":"number","format":"double","description":"Customer fit score"},"segment":{"type":"string","description":"Customer fit segment"},"signals":{"type":"string","description":"Customer fit signals"}}},"Common.Models.LikelihoodToBuy":{"type":"object","required":["score","segment"],"properties":{"score":{"type":"number","format":"double","description":"Likelihood to buy score"},"segment":{"type":"string","description":"Likelihood to buy segment"}}},"Common.Models.AggregationValue":{"type":"object","required":["aggregation_name_display","aggregation_value"],"properties":{"aggregation_name_display":{"type":"string","description":"Display name for the aggregation"},"aggregation_value":{"type":"number","format":"double","description":"Aggregation value"}}}}},"paths":{"/persons/{mk_id}":{"get":{"operationId":"Persons_getPerson","summary":"Get Person By Id","description":"Retrieve comprehensive person information including job details, company background, engagement scoring, and activity metrics.","parameters":[{"name":"mk_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Models.PersonDetail"}}}}},"tags":["Persons"]}}}} ``` ## Get Person Activities > Get activities associated with a person including email opens, website visits, content downloads, and meeting attendance. Filter by activity type or date range to understand engagement patterns and optimize outreach timing. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Persons"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Common.Models.PersonActivityResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Common.Models.PersonActivity"},"description":"Person activity data"},"meta":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Meta"}],"description":"Metadata"}}},"Common.Models.PersonActivity":{"type":"object","allOf":[{"$ref":"#/components/schemas/Common.Models.ActivityBase"}]},"Common.Models.ActivityBase":{"type":"object","required":["event_id","event","event_display","event_timestamp","activity_type","account_id"],"properties":{"event_id":{"type":"string","description":"Event ID"},"event":{"type":"string","description":"Event name"},"event_display":{"type":"string","description":"Event display name"},"event_timestamp":{"type":"string","description":"Event timestamp"},"activity_type":{"type":"string","description":"Activity type"},"account_id":{"type":"string","description":"Account ID"}}},"Common.Models.Meta":{"type":"object","properties":{"limit":{"type":"integer","format":"int32","description":"Number of results returned"},"total":{"type":"integer","format":"int32","description":"Total number of results available"},"has_next_page":{"type":"boolean","description":"Whether there are more results"},"next_cursor":{"type":"integer","format":"int32","description":"Next cursor for pagination"}}},"Common.Models.PersonActivitySearchRequest":{"type":"object","properties":{"limit":{"type":"integer","format":"int32","description":"Number of results to return"},"cursor":{"type":"integer","format":"int32","description":"Cursor for pagination"},"search":{"type":"string","description":"Search query"},"filters":{"type":"array","items":{"$ref":"#/components/schemas/Common.Models.PersonActivityFilter"},"description":"Filters to apply"},"filterLogic":{"type":"string","enum":["AND","OR"],"description":"Filter logic"},"sort":{"type":"array","items":{"$ref":"#/components/schemas/Common.Models.SortingParam"},"description":"Sorting parameters"}}},"Common.Models.PersonActivityFilter":{"type":"object","required":["property","operator","value"],"properties":{"property":{"allOf":[{"$ref":"#/components/schemas/Common.Models.PersonActivityFilterProperty"}],"description":"Property to filter by"},"operator":{"allOf":[{"$ref":"#/components/schemas/Common.Models.FilterOperator"}],"description":"Filter operator"},"value":{"anyOf":[{"type":"string"},{"type":"integer","format":"int32"},{"type":"number","format":"double"},{"type":"boolean"},{"type":"array","items":{"type":"string"}}],"description":"Filter value"}}},"Common.Models.PersonActivityFilterProperty":{"type":"string","enum":["event","event_display","event_timestamp","activity_type"]},"Common.Models.FilterOperator":{"type":"string","enum":["IS","IS_NOT","GT","GTE","LT","LTE","IN","NOT_IN","BETWEEN","NOT_BETWEEN","LIKE","NOT_LIKE","IS_NULL","IS_NOT_NULL","CONTAINS","NOT_CONTAINS","STARTS_WITH","ENDS_WITH","IS_EMPTY","IS_NOT_EMPTY"]},"Common.Models.SortingParam":{"type":"object","required":["sort_by","sort_order"],"properties":{"sort_by":{"type":"string","description":"Field to sort by"},"sort_order":{"type":"string","enum":["asc","desc"],"description":"Sort order"}}}}},"paths":{"/persons/{mk_id}/activities":{"post":{"operationId":"Persons_getPersonActivities","summary":"Get Person Activities","description":"Get activities associated with a person including email opens, website visits, content downloads, and meeting attendance. Filter by activity type or date range to understand engagement patterns and optimize outreach timing.","parameters":[{"name":"mk_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Models.PersonActivityResponse"}}}}},"tags":["Persons"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Models.PersonActivitySearchRequest"}}}}}}}} ``` # Enrichment The Enrichment API allows you to retrieve valuable company insights based on a domain name. It provides structured data such as hiring activity, technologies usage and more. ## Search job postings from a company > Find a company's job openings to identify growth, expansion plans and relevant roles they are hiring for. Filter by department, seniority, or keywords. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Enrichment"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"JobPostingSearchResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/JobPosting"},"description":"Array of job posting results"},"meta":{"allOf":[{"$ref":"#/components/schemas/SearchMeta"}],"description":"Metadata about the search results"}}},"JobPosting":{"type":"object","required":["company_domain","job_opening_title","job_opening_url","event","event_on","first_event_on"],"properties":{"company_domain":{"type":"string","description":"Company domain"},"job_opening_title":{"type":"string","description":"Job opening title"},"job_opening_url":{"type":"string","description":"URL to the job posting"},"keywords":{"type":"string","description":"Keywords associated with the job"},"categories":{"type":"string","description":"Categories associated with the job"},"location":{"type":"string","description":"Location of the job"},"event":{"type":"string","description":"Event type"},"event_on":{"type":"string","description":"Date when the event occurred"},"first_event_on":{"type":"string","description":"Date when the first event occurred"}}},"SearchMeta":{"type":"object","properties":{"limit":{"type":"integer","format":"int32","description":"Number of results requested"},"total":{"type":"integer","format":"int32","description":"Total number of results available"},"has_next_page":{"type":"boolean","description":"Whether there are more results available"},"next_cursor":{"type":"integer","format":"int32","description":"Cursor for the next page of results"}}},"Common.Errors.ValidationError":{"type":"object","required":["detail"],"properties":{"detail":{"type":"array","items":{"type":"object","properties":{"loc":{"type":"array","prefixItems":[{"anyOf":[{"type":"string"},{"type":"integer","format":"int32"}]}],"description":"What part is invalid"},"msg":{"type":"string","description":"Message discribing the error"},"type":{"type":"string","description":"Type of the error"},"input":{},"ctx":{}},"required":["loc","msg","type"]}}},"description":"Error return when body sent is invalid"},"JobPostingSearchRequestBody":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"Domain to search for job postings"},"limit":{"type":"integer","format":"int32","description":"Maximum number of results to return","default":20},"cursor":{"type":"integer","format":"int32","description":"Cursor for pagination","default":0},"search":{"type":"string","description":"Free text search query"},"filters":{"type":"array","items":{"$ref":"#/components/schemas/JobPostingFilter"},"description":"Array of filters to apply to the search"},"filter_logic":{"allOf":[{"$ref":"#/components/schemas/FilterLogic"}],"description":"Logic to apply between filters (AND or OR)","default":"AND"},"sort":{"type":"array","items":{"$ref":"#/components/schemas/SortingParam"},"description":"Array of sorting parameters"}}},"JobPostingFilter":{"type":"object","required":["property","operator","value"],"properties":{"property":{"allOf":[{"$ref":"#/components/schemas/JobPostingFilterField"}],"description":"Property to filter on"},"operator":{"allOf":[{"$ref":"#/components/schemas/FilterOperator"}],"description":"Operator to apply for the filter"},"value":{"anyOf":[{"type":"string"},{"type":"integer","format":"int32"},{"type":"number","format":"double"},{"type":"boolean"},{"type":"string","format":"date-time"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"integer","format":"int32"},{"type":"number","format":"double"},{"type":"boolean"},{"type":"string","format":"date-time"}]}}],"description":"Value to filter by"}}},"JobPostingFilterField":{"type":"string","enum":["job_opening_title","keywords","categories","location","event","event_on","first_event_on"]},"FilterOperator":{"type":"string","enum":["IS","IS_NOT","GT","GTE","LT","LTE","IN","NOT_IN","BETWEEN","NOT_BETWEEN","IS_NULL","IS_NOT_NULL","CONTAINS","NOT_CONTAINS","STARTS_WITH","ENDS_WITH"]},"FilterLogic":{"type":"string","enum":["AND","OR"]},"SortingParam":{"type":"object","required":["sort_by","sort_order"],"properties":{"sort_by":{"type":"string","description":"Field to sort by"},"sort_order":{"allOf":[{"$ref":"#/components/schemas/SortOrder"}],"description":"Sort order (ascending or descending)"}}},"SortOrder":{"type":"string","enum":["asc","desc"]}}},"paths":{"/enrichment/job-postings":{"post":{"operationId":"Enrichment_searchJobPostings","summary":"Search job postings from a company","description":"Find a company's job openings to identify growth, expansion plans and relevant roles they are hiring for. Filter by department, seniority, or keywords.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobPostingSearchResponse"}}}},"422":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ValidationError"}}}}},"tags":["Enrichment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobPostingSearchRequestBody"}}}}}}}} ``` # Search Search accounts or persons with filters ## Search accounts > Search for accounts with advanced filtering capabilities. Supports filtering by company attributes like domain, name, industry, employee count, funding, location, and activity levels. Includes pagination, sorting, and full-text search. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Search"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"AccountSearchResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountDetailSearch"},"description":"Account search data"},"meta":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Meta"}],"description":"Metadata"}}},"AccountDetailSearch":{"type":"object","required":["mk_id","source_system","name","domain","socials","location","scores"],"properties":{"mk_id":{"type":"string","description":"Unique identifier for the account in MadKudu"},"source_system":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SourceSystem"}],"description":"Source system information"},"name":{"type":"string","description":"Account name"},"domain":{"type":"string","description":"Account domain"},"logo":{"type":"string","description":"Logo URL"},"description":{"type":"string","description":"Account description"},"industry":{"type":"string","description":"Industry"},"founded_year":{"type":"integer","format":"int32","description":"Founded year"},"raised_amount":{"type":"number","format":"double","description":"Raised amount"},"employees_count":{"type":"integer","format":"int32","description":"Number of employees"},"active_users":{"type":"integer","format":"int32","description":"Number of active users"},"activities_count":{"type":"integer","format":"int32","description":"Total activities count"},"socials":{"allOf":[{"$ref":"#/components/schemas/Common.Models.AccountSocials"}],"description":"Social media handles"},"location":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Location"}],"description":"Location information"},"scores":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Scores"}],"description":"Scoring information"}}},"Common.Models.SourceSystem":{"type":"object","required":["id","system","object"],"properties":{"id":{"type":"string","description":"Unique identifier in the source system"},"system":{"type":"string","description":"Name of the source system"},"object":{"type":"string","description":"Object type in the source system"}}},"Common.Models.AccountSocials":{"type":"object","properties":{"linkedin_handle":{"type":"string","description":"LinkedIn company handle"},"twitter_handle":{"type":"string","description":"Twitter company handle"},"crunchbase_handle":{"type":"string","description":"Crunchbase organization handle"},"website":{"type":"string","description":"Company website URL"}}},"Common.Models.Location":{"type":"object","properties":{"country":{"type":"string","description":"Country"},"state":{"type":"string","description":"State or region"},"city":{"type":"string","description":"City"}}},"Common.Models.Scores":{"type":"object","required":["customer_fit","likelihood_to_buy"],"properties":{"customer_fit":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CustomerFit"}],"description":"Customer fit information"},"likelihood_to_buy":{"allOf":[{"$ref":"#/components/schemas/Common.Models.LikelihoodToBuy"}],"description":"Likelihood to buy information"}}},"Common.Models.CustomerFit":{"type":"object","required":["score","segment"],"properties":{"score":{"type":"number","format":"double","description":"Customer fit score"},"segment":{"type":"string","description":"Customer fit segment"},"signals":{"type":"string","description":"Customer fit signals"}}},"Common.Models.LikelihoodToBuy":{"type":"object","required":["score","segment"],"properties":{"score":{"type":"number","format":"double","description":"Likelihood to buy score"},"segment":{"type":"string","description":"Likelihood to buy segment"}}},"Common.Models.Meta":{"type":"object","properties":{"limit":{"type":"integer","format":"int32","description":"Number of results returned"},"total":{"type":"integer","format":"int32","description":"Total number of results available"},"has_next_page":{"type":"boolean","description":"Whether there are more results"},"next_cursor":{"type":"integer","format":"int32","description":"Next cursor for pagination"}}},"Common.Errors.ValidationError":{"type":"object","required":["detail"],"properties":{"detail":{"type":"array","items":{"type":"object","properties":{"loc":{"type":"array","prefixItems":[{"anyOf":[{"type":"string"},{"type":"integer","format":"int32"}]}],"description":"What part is invalid"},"msg":{"type":"string","description":"Message discribing the error"},"type":{"type":"string","description":"Type of the error"},"input":{},"ctx":{}},"required":["loc","msg","type"]}}},"description":"Error return when body sent is invalid"},"AccountSearchRequest":{"type":"object","properties":{"limit":{"type":"integer","format":"int32","description":"Number of results to return"},"cursor":{"type":"integer","format":"int32","description":"Cursor for pagination"},"search":{"type":"string","description":"Search query"},"filters":{"type":"array","items":{"$ref":"#/components/schemas/AccountSearchFilter"},"description":"Filters to apply - restricted to account fields"},"filterLogic":{"allOf":[{"$ref":"#/components/schemas/FilterLogic"}],"description":"Filter logic"},"sort":{"type":"array","items":{"$ref":"#/components/schemas/Common.Models.SortingParam"},"description":"Sorting parameters"}}},"AccountSearchFilter":{"type":"object","required":["property","operator","value"],"properties":{"property":{"type":"string","enum":["name","domain","industry","employees_count","founded_year","raised_amount","country","city","active_users","activities_count"],"description":"Property to filter by - restricted to account fields"},"operator":{"allOf":[{"$ref":"#/components/schemas/FilterOperator"}],"description":"Filter operator"},"value":{"anyOf":[{"type":"string"},{"type":"integer","format":"int32"},{"type":"number","format":"double"},{"type":"boolean"},{"type":"string","format":"date-time"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"integer","format":"int32"},{"type":"number","format":"double"},{"type":"boolean"},{"type":"string","format":"date-time"}]}}],"description":"Filter value"}}},"FilterOperator":{"type":"string","enum":["IS","IS_NOT","GT","GTE","LT","LTE","IN","NOT_IN","BETWEEN","NOT_BETWEEN","IS_NULL","IS_NOT_NULL","CONTAINS","NOT_CONTAINS","STARTS_WITH","ENDS_WITH"]},"FilterLogic":{"type":"string","enum":["AND","OR"]},"Common.Models.SortingParam":{"type":"object","required":["sort_by","sort_order"],"properties":{"sort_by":{"type":"string","description":"Field to sort by"},"sort_order":{"type":"string","enum":["asc","desc"],"description":"Sort order"}}}}},"paths":{"/search/accounts":{"post":{"operationId":"Search_searchAccounts","summary":"Search accounts","description":"Search for accounts with advanced filtering capabilities. Supports filtering by company attributes like domain, name, industry, employee count, funding, location, and activity levels. Includes pagination, sorting, and full-text search.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountSearchResponse"}}}},"422":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ValidationError"}}}}},"tags":["Search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountSearchRequest"}}}}}}}} ``` ## Search persons > Search for persons with advanced filtering capabilities. Supports filtering by personal attributes like email, name, title, persona, company domain, location, and activity levels. Includes pagination, sorting, and full-text search. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Search"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"PersonSearchResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PersonDetailSearch"},"description":"Person search data"},"meta":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Meta"}],"description":"Metadata"}}},"PersonDetailSearch":{"type":"object","required":["mk_id","source_system","email","name","company","socials","location","scores"],"properties":{"mk_id":{"type":"string","description":"Unique identifier for the person in MadKudu"},"source_system":{"allOf":[{"$ref":"#/components/schemas/Common.Models.SourceSystem"}],"description":"Source system information"},"email":{"type":"string","description":"Email address"},"name":{"type":"string","description":"Full name"},"first_name":{"type":"string","description":"First name"},"last_name":{"type":"string","description":"Last name"},"title":{"type":"string","description":"Job title"},"persona":{"type":"string","description":"Persona"},"avatar":{"type":"string","description":"Avatar URL"},"company":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CompanyReference"}],"description":"Company information"},"socials":{"allOf":[{"$ref":"#/components/schemas/Common.Models.PersonSocials"}],"description":"Social media handles"},"location":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Location"}],"description":"Location information"},"has_left_company":{"type":"boolean","description":"Has left company"},"scores":{"allOf":[{"$ref":"#/components/schemas/Common.Models.Scores"}],"description":"Scoring information"},"activities":{"description":"Activities information"}}},"Common.Models.SourceSystem":{"type":"object","required":["id","system","object"],"properties":{"id":{"type":"string","description":"Unique identifier in the source system"},"system":{"type":"string","description":"Name of the source system"},"object":{"type":"string","description":"Object type in the source system"}}},"Common.Models.CompanyReference":{"type":"object","required":["domain","mk_id"],"properties":{"domain":{"type":"string","description":"Domain of the company"},"mk_id":{"type":"string","description":"MadKudu ID of the company"}}},"Common.Models.PersonSocials":{"type":"object","properties":{"linkedin_handle":{"type":"string","description":"LinkedIn handle"},"twitter_handle":{"type":"string","description":"Twitter handle"},"crunchbase_handle":{"type":"string","description":"Crunchbase handle"},"website":{"type":"string","description":"Website URL"}}},"Common.Models.Location":{"type":"object","properties":{"country":{"type":"string","description":"Country"},"state":{"type":"string","description":"State or region"},"city":{"type":"string","description":"City"}}},"Common.Models.Scores":{"type":"object","required":["customer_fit","likelihood_to_buy"],"properties":{"customer_fit":{"allOf":[{"$ref":"#/components/schemas/Common.Models.CustomerFit"}],"description":"Customer fit information"},"likelihood_to_buy":{"allOf":[{"$ref":"#/components/schemas/Common.Models.LikelihoodToBuy"}],"description":"Likelihood to buy information"}}},"Common.Models.CustomerFit":{"type":"object","required":["score","segment"],"properties":{"score":{"type":"number","format":"double","description":"Customer fit score"},"segment":{"type":"string","description":"Customer fit segment"},"signals":{"type":"string","description":"Customer fit signals"}}},"Common.Models.LikelihoodToBuy":{"type":"object","required":["score","segment"],"properties":{"score":{"type":"number","format":"double","description":"Likelihood to buy score"},"segment":{"type":"string","description":"Likelihood to buy segment"}}},"Common.Models.Meta":{"type":"object","properties":{"limit":{"type":"integer","format":"int32","description":"Number of results returned"},"total":{"type":"integer","format":"int32","description":"Total number of results available"},"has_next_page":{"type":"boolean","description":"Whether there are more results"},"next_cursor":{"type":"integer","format":"int32","description":"Next cursor for pagination"}}},"Common.Errors.ValidationError":{"type":"object","required":["detail"],"properties":{"detail":{"type":"array","items":{"type":"object","properties":{"loc":{"type":"array","prefixItems":[{"anyOf":[{"type":"string"},{"type":"integer","format":"int32"}]}],"description":"What part is invalid"},"msg":{"type":"string","description":"Message discribing the error"},"type":{"type":"string","description":"Type of the error"},"input":{},"ctx":{}},"required":["loc","msg","type"]}}},"description":"Error return when body sent is invalid"},"PersonSearchRequest":{"type":"object","properties":{"limit":{"type":"integer","format":"int32","description":"Number of results to return"},"cursor":{"type":"integer","format":"int32","description":"Cursor for pagination"},"search":{"type":"string","description":"Search query"},"filters":{"type":"array","items":{"$ref":"#/components/schemas/PersonSearchFilter"},"description":"Filters to apply - restricted to person fields"},"filterLogic":{"allOf":[{"$ref":"#/components/schemas/FilterLogic"}],"description":"Filter logic"},"sort":{"type":"array","items":{"$ref":"#/components/schemas/Common.Models.SortingParam"},"description":"Sorting parameters"}}},"PersonSearchFilter":{"type":"object","required":["property","operator","value"],"properties":{"property":{"type":"string","enum":["email","first_name","last_name","name","title","persona","company_domain","country","state","city","activities","has_left_company"],"description":"Property to filter by - restricted to person fields"},"operator":{"allOf":[{"$ref":"#/components/schemas/FilterOperator"}],"description":"Filter operator"},"value":{"anyOf":[{"type":"string"},{"type":"integer","format":"int32"},{"type":"number","format":"double"},{"type":"boolean"},{"type":"string","format":"date-time"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"integer","format":"int32"},{"type":"number","format":"double"},{"type":"boolean"},{"type":"string","format":"date-time"}]}}],"description":"Filter value"}}},"FilterOperator":{"type":"string","enum":["IS","IS_NOT","GT","GTE","LT","LTE","IN","NOT_IN","BETWEEN","NOT_BETWEEN","IS_NULL","IS_NOT_NULL","CONTAINS","NOT_CONTAINS","STARTS_WITH","ENDS_WITH"]},"FilterLogic":{"type":"string","enum":["AND","OR"]},"Common.Models.SortingParam":{"type":"object","required":["sort_by","sort_order"],"properties":{"sort_by":{"type":"string","description":"Field to sort by"},"sort_order":{"type":"string","enum":["asc","desc"],"description":"Sort order"}}}}},"paths":{"/search/persons":{"post":{"operationId":"Search_searchPersons","summary":"Search persons","description":"Search for persons with advanced filtering capabilities. Supports filtering by personal attributes like email, name, title, persona, company domain, location, and activity levels. Includes pagination, sorting, and full-text search.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonSearchResponse"}}}},"422":{"description":"Client error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.ValidationError"}}}}},"tags":["Search"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonSearchRequest"}}}}}}}} ``` # Sourcing Discover new prospects from your favorite data providers (Apollo, Cognism, and ZoomInfo), who aren't already in your CRM You define who you're looking for based on criteria like company domain, job title, location, and seniority level. We go fetch them for you with the Discover endpoint. Then use the Enrich endpoints for the ones you're interested in to get their email, phone numbers and other contact details. **Pre-requisite**: you must have your Apollo, ZoomInfo or Cognism account connected to your MadKudu workspace ([see how to connect here](https://help.madkudu.com/docs/apolloio?highlight=apollo))
## Get available sourcing providers > Retrieves a list of all available sourcing data providers and their connection status for the current tenant. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Sourcing"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"SourcingProvider":{"type":"object","required":["provider","isConnected"],"properties":{"provider":{"type":"string","enum":["apollo","cognism","zoominfo"],"description":"The name of the sourcing provider"},"isConnected":{"type":"boolean","description":"Whether the provider is properly configured and connected for this tenant"}}}}},"paths":{"/sourcing/providers":{"get":{"operationId":"Sourcing_getProviders","summary":"Get available sourcing providers","description":"Retrieves a list of all available sourcing data providers and their connection status for the current tenant.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SourcingProvider"}}}}}},"tags":["Sourcing"]}}}} ``` ## Discover persons using data providers > Discovers persons using various data providers with optional filtering criteria including company domain, job title, location, and seniority level. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Sourcing"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"PersonDiscoverResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SourcingPersonResult"},"description":"Array of discovered persons"},"pagination":{"allOf":[{"$ref":"#/components/schemas/PersonDiscoverResponsePagination"}],"description":"Pagination information"}}},"SourcingPersonResult":{"type":"object","required":["id","first_name","last_name","provider"],"properties":{"id":{"type":"string","description":"Provider-specific person ID"},"first_name":{"type":"string","description":"First name"},"last_name":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address (available after enrichment)"},"phone":{"type":"string","description":"Phone number (available after enrichment)"},"photo":{"type":"string","description":"Photo URL"},"title":{"type":"string","description":"Job title"},"company_name":{"type":"string","description":"Company name"},"company_domain":{"type":"string","description":"Company domain"},"linkedin_url":{"type":"string","description":"LinkedIn profile URL"},"provider":{"type":"string","enum":["apollo","cognism","zoominfo"],"description":"Data provider used"},"enrich_token":{"type":"string","description":"Token for enrichment (optional)"}}},"PersonDiscoverResponsePagination":{"type":"object","required":["size","total"],"properties":{"next_page":{"type":"integer","format":"int32","description":"Next page number (for Apollo/ZoomInfo)"},"page":{"type":"integer","format":"int32","description":"Current page number"},"size":{"type":"integer","format":"int32","description":"Number of results per page"},"total":{"type":"integer","format":"int32","description":"Total number of results available"},"next_cursor":{"type":"string","description":"Next cursor for pagination (for Cognism)"}}},"PersonDiscoverRequest":{"anyOf":[{"$ref":"#/components/schemas/ApolloDiscoverRequest"},{"$ref":"#/components/schemas/ZoomInfoDiscoverRequest"},{"$ref":"#/components/schemas/CognismDiscoverRequest"}]},"ApolloDiscoverRequest":{"type":"object","required":["provider"],"properties":{"provider":{"type":"string","enum":["apollo"],"description":"Data provider"},"filters":{"allOf":[{"$ref":"#/components/schemas/ApolloFilters"}],"description":"Apollo-specific filtering criteria"},"pagination":{"allOf":[{"$ref":"#/components/schemas/PersonDiscoverPagination"}],"description":"Pagination parameters"}}},"ApolloFilters":{"type":"object","properties":{"person_titles":{"type":"array","items":{"type":"string"},"description":"Job titles held by the people you want to find. Use lowercase for better matching accuracy (e.g., 'software engineer', 'marketing manager')"},"include_similar_titles":{"type":"boolean","description":"Whether people with similar job titles are included"},"q_keywords":{"type":"string","description":"Keywords to search for"},"person_locations":{"type":"array","items":{"type":"string"},"description":"Location where people live (cities, US states, countries)"},"person_seniorities":{"type":"array","items":{"type":"string"},"description":"Job seniority levels"},"organization_locations":{"type":"array","items":{"type":"string"},"description":"Company headquarters locations"},"q_organization_domains_list":{"type":"array","items":{"type":"string"},"description":"Domain names for person's current or previous employer"},"contact_email_status":{"type":"array","items":{"type":"string"},"description":"Email statuses for people"},"organization_ids":{"type":"array","items":{"type":"string"},"description":"Apollo company IDs to include in search"},"organization_num_employees_ranges":{"type":"array","items":{"type":"string"},"description":"Number of employees range for person's current company"},"revenue_range_min":{"type":"integer","format":"int32","description":"Minimum revenue for person's current employer"},"revenue_range_max":{"type":"integer","format":"int32","description":"Maximum revenue for person's current employer"},"currently_using_all_of_technology_uids":{"type":"array","items":{"type":"string"},"description":"Technologies current employer must use (all of)"},"currently_using_any_of_technology_uids":{"type":"array","items":{"type":"string"},"description":"Technologies current employer must use (any of)"},"currently_not_using_any_of_technology_uids":{"type":"array","items":{"type":"string"},"description":"Technologies current employer must not use"},"q_organization_job_titles":{"type":"array","items":{"type":"string"},"description":"Job titles in active job postings at current employer"},"organization_job_locations":{"type":"array","items":{"type":"string"},"description":"Locations of jobs being recruited by employer"},"organization_num_jobs_range_min":{"type":"integer","format":"int32","description":"Minimum number of active job postings at current employer"},"organization_num_jobs_range_max":{"type":"integer","format":"int32","description":"Maximum number of active job postings at current employer"},"organization_job_posted_at_range_min":{"type":"string","format":"date","description":"Earliest date when jobs were posted by current employer"},"organization_job_posted_at_range_max":{"type":"string","format":"date","description":"Latest date when jobs were posted by current employer"}}},"PersonDiscoverPagination":{"type":"object","properties":{"page":{"type":"integer","format":"int32","minimum":1,"description":"Page number (for Apollo/ZoomInfo)"},"size":{"type":"integer","format":"int32","minimum":1,"maximum":100,"description":"Number of results per page"},"cursor":{"type":"string","description":"Cursor for pagination (for Cognism)"}}},"ZoomInfoDiscoverRequest":{"type":"object","required":["provider"],"properties":{"provider":{"type":"string","enum":["zoominfo"],"description":"Data provider"},"filters":{"allOf":[{"$ref":"#/components/schemas/ZoomInfoFilters"}],"description":"ZoomInfo-specific filtering criteria"},"pagination":{"allOf":[{"$ref":"#/components/schemas/PersonDiscoverPagination"}],"description":"Pagination parameters"}}},"ZoomInfoFilters":{"type":"object","properties":{"rpp":{"type":"integer","format":"int32","minimum":1,"maximum":100,"description":"Limits the results returned to the given number of results per page. Default is 25."},"page":{"type":"integer","format":"int32","minimum":1,"description":"Provides the results for the given page, used in conjunction with rpp"},"sortBy":{"type":"string","enum":["contactAccuracyScore","lastName","companyName","hierarchy","sourceCount","lastMentioned","relevance"],"description":"Sort results by valid output fields"},"sortOrder":{"type":"string","enum":["asc","ascending","desc","descending"],"description":"Sort order for results"},"personId":{"type":"string","description":"Unique ZoomInfo identifier for the contact. Can include a comma-separated list."},"emailAddress":{"type":"string","description":"Work email address for the contact"},"supplementalEmail":{"type":"array","items":{"type":"string"},"description":"Supplemental email address for the contact"},"hashedEmail":{"type":"string","description":"Hashed email value for the contact (MD5, SHA1, SHA256, SHA512)"},"phone":{"type":"array","items":{"type":"string"},"description":"List of person phones or mobile numbers"},"fullName":{"type":"string","description":"Contact full name"},"firstName":{"type":"string","description":"Contact first name"},"middleInitial":{"type":"string","description":"Contact middle initial"},"lastName":{"type":"string","description":"Contact last name"},"jobTitle":{"type":"string","description":"Contact title at current place of employment. Use OR to input multiple job titles."},"excludeJobTitle":{"type":"string","description":"Exclude comma-separated list of job titles"},"managementLevel":{"type":"string","description":"Contact management level at current place of employment"},"excludeManagementLevel":{"type":"string","description":"Exclude contact based on management level"},"department":{"type":"string","description":"Contact department at current place of employment"},"jobFunction":{"type":"string","description":"Contact job function at their current place of employment"},"boardMember":{"type":"string","description":"Exclude or include board members from search results"},"executivesOnly":{"type":"boolean","description":"Return only executives"},"excludePartialProfiles":{"type":"boolean","description":"Exclude contacts with a partial profile from search results"},"contactAccuracyScore":{"allOf":[{"$ref":"#/components/schemas/ZoomInfoAccuracyScoreRange"}],"description":"Contact accuracy score range"},"hasBeenNotified":{"type":"string","enum":["exclude","include","only"],"description":"Contacts who have been notified of inclusion in ZoomInfo's database"},"lastUpdatedDateAfter":{"type":"string","format":"date","description":"The date after which the contact's profile was last updated (YYYY-MM-DD)"},"validDateAfter":{"type":"string","format":"date","description":"The date after which the contact's profile was last validated (YYYY-MM-DD)"},"lastUpdatedInMonths":{"type":"integer","format":"int32","minimum":1,"description":"Number of months within which the contact's profile was last updated"},"positionStartDateMin":{"type":"string","format":"date","description":"Minimum date for when a contact began current employment (YYYY-MM-DD)"},"positionStartDateMax":{"type":"string","format":"date","description":"Maximum date for when a contact began current employment (YYYY-MM-DD)"},"companyPastOrPresent":{"type":"string","enum":["present","past","pastAndPresent"],"description":"Returns companies based on a contact's work history"},"school":{"type":"string","description":"Contact educational institution"},"degree":{"type":"string","description":"Contact education degree"},"locationCompanyId":{"type":"array","items":{"type":"string"},"description":"Searches by contact's location IDs"},"companyId":{"type":"string","description":"ZoomInfo unique identifier for the company. Will accept a comma-separated list."},"companyName":{"type":"string","description":"Company name. Can use OR and NOT operators to include or exclude companies"},"companyWebsite":{"type":"string","description":"URL to the company website"},"companyTicker":{"type":"array","items":{"type":"string"},"description":"Company stock ticker symbol"},"companyDescription":{"type":"string","description":"Text description unique to the company"},"parentId":{"type":"string","description":"ZoomInfo Company ID for parent company"},"ultimateParentId":{"type":"string","description":"ZoomInfo Company ID for ultimate parent company"},"companyType":{"type":"string","description":"Company type (private, public, etc.)"},"address":{"type":"string","description":"Company address"},"street":{"type":"string","description":"Company street"},"state":{"type":"string","description":"Company state (U.S.) or province (Canada)"},"zipCode":{"type":"string","description":"Zip Code of the company's primary address"},"country":{"type":"string","description":"Country for the company's primary address"},"continent":{"type":"string","description":"Continent for the company's primary address"},"zipCodeRadiusMiles":{"type":"string","description":"Geographical radius in miles from the zipCode provided"},"metroRegion":{"type":"string","description":"Company metro area"},"excludedRegions":{"type":"string","description":"Exclude a company metro area"},"locationSearchType":{"type":"string","enum":["PersonOrHQ","PersonAndHQ","Person","HQ","PersonThenHQ"],"description":"Location criteria for search"},"hashTagString":{"type":"string","description":"Hash tags for a company"},"techAttributeTagList":{"type":"string","description":"Technology product tags using numerical dot notation"},"subUnitTypes":{"type":"string","description":"Company sub types (e.g., division, subsidiary)"},"companyStructureIncludedSubUnitTypes":{"type":"string","description":"Company hierarchical structure"},"primaryIndustriesOnly":{"type":"boolean","description":"Used with industryCodes - when true, results must have specified industries as primary"},"industryCodes":{"type":"string","description":"Top-level industry that the contact works in"},"industryKeywords":{"type":"string","description":"Industry keywords associated with a company"},"sicCodes":{"type":"string","description":"Standard Industrial Classification four-digit codes"},"naicsCodes":{"type":"string","description":"North American Industry Classification System codes"},"revenue":{"type":"string","description":"Annual revenue range"},"revenueRange":{"allOf":[{"$ref":"#/components/schemas/ZoomInfoRevenueRange"}],"description":"Annual revenue range in U.S. dollars"},"employeeCount":{"type":"string","description":"Employee count range"},"employeeRange":{"allOf":[{"$ref":"#/components/schemas/ZoomInfoEmployeeRange"}],"description":"Employee count range (granular)"},"companyRanking":{"type":"string","description":"Company ranking list (e.g., Fortune 500)"},"zoominfoContacts":{"allOf":[{"$ref":"#/components/schemas/ZoomInfoContactRange"}],"description":"Number of ZoomInfo contacts associated with company"},"oneYearEmployeeGrowthRate":{"allOf":[{"$ref":"#/components/schemas/ZoomInfoGrowthRateRange"}],"description":"One year employee growth rate range"},"twoYearEmployeeGrowthRate":{"allOf":[{"$ref":"#/components/schemas/ZoomInfoGrowthRateRange"}],"description":"Two year employee growth rate range"},"fundingAmount":{"allOf":[{"$ref":"#/components/schemas/ZoomInfoFundingRange"}],"description":"Funding amount range in thousands"},"fundingStartDate":{"type":"string","format":"date","description":"Start date of the funding (YYYY-MM-DD)"},"fundingEndDate":{"type":"string","format":"date","description":"End date of the funding (YYYY-MM-DD)"},"webReferences":{"type":"array","items":{"type":"string"},"description":"List of web references for a contact"},"filterByBuyingCommittee":{"type":"boolean","description":"Boolean flag for Buying Committee filtering"},"techSkills":{"type":"array","items":{"type":"string"},"description":"List of technology skills for a contact"},"yearsOfExperience":{"type":"string","description":"Years of overall experience"},"engagementStartDate":{"type":"string","format":"date","description":"Engagement start date (YYYY-MM-DD)"},"engagementEndDate":{"type":"string","format":"date","description":"Engagement end date (YYYY-MM-DD)"},"engagementType":{"type":"array","items":{"type":"string","enum":["email","phone","online meeting"]},"description":"List of engagement types to search for"}}},"ZoomInfoAccuracyScoreRange":{"type":"object","properties":{"min":{"type":"integer","format":"int32","minimum":70,"maximum":99,"description":"Minimum accuracy score (70-99)"},"max":{"type":"integer","format":"int32","minimum":70,"maximum":99,"description":"Maximum accuracy score (70-99)"}}},"ZoomInfoRevenueRange":{"type":"object","properties":{"min":{"type":"integer","format":"int64","description":"Minimum annual revenue in U.S. dollars"},"max":{"type":"integer","format":"int64","description":"Maximum annual revenue in U.S. dollars"}}},"ZoomInfoEmployeeRange":{"type":"object","properties":{"min":{"type":"integer","format":"int32","description":"Minimum employee count"},"max":{"type":"integer","format":"int32","description":"Maximum employee count"}}},"ZoomInfoContactRange":{"type":"object","properties":{"min":{"type":"integer","format":"int32","description":"Minimum number of ZoomInfo contacts"},"max":{"type":"integer","format":"int32","description":"Maximum number of ZoomInfo contacts"}}},"ZoomInfoGrowthRateRange":{"type":"object","properties":{"min":{"type":"string","description":"Minimum growth rate"},"max":{"type":"string","description":"Maximum growth rate"}}},"ZoomInfoFundingRange":{"type":"object","properties":{"min":{"type":"integer","format":"int32","description":"Minimum funding amount in thousands"},"max":{"type":"integer","format":"int32","description":"Maximum funding amount in thousands"}}},"CognismDiscoverRequest":{"type":"object","required":["provider"],"properties":{"provider":{"type":"string","enum":["cognism"],"description":"Data provider"},"filters":{"allOf":[{"$ref":"#/components/schemas/CognismFilters"}],"description":"Cognism-specific filtering criteria"},"pagination":{"allOf":[{"$ref":"#/components/schemas/PersonDiscoverPagination"}],"description":"Pagination parameters"}}},"CognismFilters":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"description":"Contact ids"},"fullName":{"type":"string","description":"Contact full name"},"firstName":{"type":"string","description":"Contact first name"},"lastName":{"type":"string","description":"Contact last name"},"jobTitles":{"type":"array","items":{"type":"string"},"description":"Contact current position job titles"},"excludeJobTitles":{"type":"array","items":{"type":"string"},"description":"Contact current position excluded job titles"},"seniority":{"type":"array","items":{"type":"string","enum":["Manager","Director","Partner","CXO","Owner","VP"]},"description":"Contact current position seniority"},"jobFunctions":{"type":"array","items":{"type":"string","enum":["Oversight","Technology","Operations","Sales","Marketing","Client Success","HR","Accounting","Business","Production"]},"description":"Contact current position job functions"},"managementLevel":{"type":"array","items":{"type":"string","enum":["Entry-Level","Team-Lead","Experienced Staff","Executive-Level","Senior Leadership","Middle-Management","CxO"]},"description":"Contact current position management levels"},"regions":{"type":"array","items":{"type":"string"},"description":"Contact location world regions"},"countries":{"type":"array","items":{"type":"string"},"description":"Contact location countries"},"excludeCountries":{"type":"array","items":{"type":"string"},"description":"Contact location excluded countries"},"states":{"type":"array","items":{"type":"string"},"description":"Contact location states"},"excludeStates":{"type":"array","items":{"type":"string"},"description":"Contact location excluded states"},"cities":{"type":"array","items":{"type":"string"},"description":"Contact location cities"},"excludeCities":{"type":"array","items":{"type":"string"},"description":"Contact location excluded cities"},"zip":{"type":"array","items":{"type":"string"},"description":"Contact location zip codes"},"skills":{"type":"array","items":{"type":"string"},"description":"Contact skills"},"excludeSkills":{"type":"array","items":{"type":"string"},"description":"Contact excluded skills"},"linkedinUrl":{"type":"string","description":"Contact LinkedIn URL"},"education":{"allOf":[{"$ref":"#/components/schemas/CognismEducation"}],"description":"Contact education information"},"mobilePhoneNumbers":{"allOf":[{"$ref":"#/components/schemas/CognismPhoneQuality"}],"description":"Search contacts with mobile phone numbers"},"directPhoneNumbers":{"allOf":[{"$ref":"#/components/schemas/CognismPhoneQuality"}],"description":"Search contacts with direct phone numbers"},"emailQuality":{"allOf":[{"$ref":"#/components/schemas/CognismEmailQuality"}],"description":"Search contacts with email quality"},"sha256":{"type":"array","items":{"type":"string"},"description":"Search contacts by sha256 hashed email"},"lastConfirmed":{"allOf":[{"$ref":"#/components/schemas/CognismDateRange"}],"description":"Contact profile time updated range"},"account":{"allOf":[{"$ref":"#/components/schemas/CognismAccountFilters"}],"description":"Contact current account filters"},"searchOptions":{"allOf":[{"$ref":"#/components/schemas/CognismSearchOptions"}],"description":"Search options"}}},"CognismEducation":{"type":"object","properties":{"schools":{"type":"array","items":{"type":"string"},"description":"Contact education school names"},"degrees":{"type":"array","items":{"type":"string"},"description":"Contact education degree names"}}},"CognismPhoneQuality":{"type":"object","properties":{"medium":{"type":"boolean","description":"Search contacts with medium quality phone numbers"},"high":{"type":"boolean","description":"Search contacts with high quality phone numbers"},"highPlus":{"type":"boolean","description":"Search contacts with highPlus quality phone numbers"}}},"CognismEmailQuality":{"type":"object","properties":{"medium":{"type":"boolean","description":"Search contacts with medium quality email"},"high":{"type":"boolean","description":"Search contacts with high quality email"},"highPlus":{"type":"boolean","description":"Search contacts with highPlus quality email"}}},"CognismDateRange":{"type":"object","properties":{"from":{"type":"integer","format":"int64","description":"Start timestamp (Unix timestamp in milliseconds)"},"to":{"type":"integer","format":"int64","description":"End timestamp (Unix timestamp in milliseconds)"}}},"CognismAccountFilters":{"type":"object","properties":{"names":{"type":"array","items":{"type":"string"},"description":"Contact current account names"},"excludeNames":{"type":"array","items":{"type":"string"},"description":"Contact current account exclude names"},"domains":{"type":"array","items":{"type":"string"},"description":"Contact current account domains"},"excludeDomains":{"type":"array","items":{"type":"string"},"description":"Contact current account exclude domains"},"websites":{"type":"array","items":{"type":"string"},"description":"Contact current account websites"},"description":{"type":"string","description":"Contact current account description keyword"},"shortDescription":{"type":"string","description":"Contact current account short description keyword"},"keywords":{"type":"array","items":{"type":"string"},"description":"Contact current account keywords"},"revenue":{"allOf":[{"$ref":"#/components/schemas/CognismRevenueRange"}],"description":"Contact current account revenue range"},"founded":{"allOf":[{"$ref":"#/components/schemas/CognismFoundedRange"}],"description":"Contact current account founded year range"},"types":{"type":"array","items":{"type":"string","enum":["Public Company","Educational","Educational Institution","Government Agency","Partnership","Privately Held","Self-Employed","non profit"]},"description":"Contact current account types"},"regions":{"type":"array","items":{"type":"string"},"description":"Contact current account world regions"},"countries":{"type":"array","items":{"type":"string"},"description":"Contact current account countries"},"excludeCountries":{"type":"array","items":{"type":"string"},"description":"Contact current account excluded countries"},"states":{"type":"array","items":{"type":"string"},"description":"Contact current account states"},"excludeStates":{"type":"array","items":{"type":"string"},"description":"Contact current account excluded states"},"cities":{"type":"array","items":{"type":"string"},"description":"Contact current account cities"},"excludeCities":{"type":"array","items":{"type":"string"},"description":"Contact current account excluded cities"},"zip":{"type":"array","items":{"type":"string"},"description":"Contact current account zip codes"},"industries":{"type":"array","items":{"type":"string"},"description":"Contact current account industries"},"excludeIndustries":{"type":"array","items":{"type":"string"},"description":"Contact current account excluded industries"},"sic":{"type":"array","items":{"type":"string"},"description":"Contact current account SIC codes"},"isic":{"type":"array","items":{"type":"string"},"description":"Contact current account ISIC codes"},"naics":{"type":"array","items":{"type":"string"},"description":"Contact current account NAICS codes"},"headcount":{"allOf":[{"$ref":"#/components/schemas/CognismHeadcountRange"}],"description":"Contact current account headcount range"},"technologies":{"type":"array","items":{"type":"string"},"description":"Contact current account technologies used"},"excludedTechnologies":{"type":"array","items":{"type":"string"},"description":"Contact current account excluded technologies"},"lastConfirmed":{"allOf":[{"$ref":"#/components/schemas/CognismDateRange"}],"description":"Contact current account time updated range"},"hqPhoneNumbers":{"allOf":[{"$ref":"#/components/schemas/CognismPhoneQuality"}],"description":"Search contacts with account having HQ phone numbers"},"officePhoneNumbers":{"allOf":[{"$ref":"#/components/schemas/CognismPhoneQuality"}],"description":"Search contacts with account having office phone numbers"}}},"CognismRevenueRange":{"type":"object","properties":{"from":{"type":"integer","format":"int64","description":"Revenue range minimum"},"to":{"type":"integer","format":"int64","description":"Revenue range maximum"}}},"CognismFoundedRange":{"type":"object","properties":{"from":{"type":"integer","format":"int32","description":"Founded year range minimum"},"to":{"type":"integer","format":"int32","description":"Founded year range maximum"}}},"CognismHeadcountRange":{"type":"object","properties":{"from":{"type":"integer","format":"int32","description":"Headcount minimum"},"to":{"type":"integer","format":"int32","description":"Headcount maximum"}}},"CognismSearchOptions":{"type":"object","properties":{"match_exact_job_title":{"type":"boolean","description":"Match exact job title"},"ai_job_title":{"type":"boolean","description":"AI expansion of job titles"},"sort_fields":{"type":"array","items":{"type":"string","enum":["LastConfirmedContactDESC","LastConfirmedContactASC","EmailQualityDESC","EmailQualityASC","ProfileScoreDESC","ProfileScoreASC"]},"description":"Sort fields"}}}}},"paths":{"/sourcing/persons/discover":{"post":{"operationId":"Sourcing_discoverPersons","summary":"Discover persons using data providers","description":"Discovers persons using various data providers with optional filtering criteria including company domain, job title, location, and seniority level.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonDiscoverResponse"}}}}},"tags":["Sourcing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonDiscoverRequest"}}}}}}}} ``` ## Enrich person with contact information > Enriches an existing person record with additional contact information (email and phone) using the specified data provider and provider-specific ID. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Sourcing"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"SourcingPersonResult":{"type":"object","required":["id","first_name","last_name","provider"],"properties":{"id":{"type":"string","description":"Provider-specific person ID"},"first_name":{"type":"string","description":"First name"},"last_name":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email address (available after enrichment)"},"phone":{"type":"string","description":"Phone number (available after enrichment)"},"photo":{"type":"string","description":"Photo URL"},"title":{"type":"string","description":"Job title"},"company_name":{"type":"string","description":"Company name"},"company_domain":{"type":"string","description":"Company domain"},"linkedin_url":{"type":"string","description":"LinkedIn profile URL"},"provider":{"type":"string","enum":["apollo","cognism","zoominfo"],"description":"Data provider used"},"enrich_token":{"type":"string","description":"Token for enrichment (optional)"}}},"PersonEnrichRequest":{"type":"object","required":["provider","provider_id"],"properties":{"provider":{"type":"string","enum":["apollo","cognism","zoominfo"],"description":"Data provider to use"},"provider_id":{"type":"string","description":"Provider-specific identifier for the person to enrich"}}}}},"paths":{"/sourcing/persons/enrich":{"post":{"operationId":"Sourcing_enrichPerson","summary":"Enrich person with contact information","description":"Enriches an existing person record with additional contact information (email and phone) using the specified data provider and provider-specific ID.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcingPersonResult"}}}}},"tags":["Sourcing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonEnrichRequest"}}}}}}}} ``` # AI Features
## AI Web Search > Performs a web search using advanced AI-powered search capabilities. This endpoint leverages the Tavily API to provide comprehensive search results with optional LLM-generated answers, image results, and content extraction. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"AI"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"WebSearchResponse":{"type":"object","required":["query","images","results","response_time"],"properties":{"query":{"type":"string","description":"Your search query"},"follow_up_questions":{"type":"string","description":"Follow-up questions related to the search"},"answer":{"type":"string","description":"The answer to your search query, generated by an LLM based on Tavily's search results. This is only available if includeAnswer is set to true"},"images":{"type":"array","items":{"$ref":"#/components/schemas/WebSearchImageResult"},"description":"A list of query-related image URLs or ImageResult objects. This is only available if includeImages is set to true"},"results":{"type":"array","items":{"$ref":"#/components/schemas/WebSearchResult"},"description":"A list of sorted search results ranked by relevancy"},"response_time":{"type":"number","format":"double","description":"Your search result response time"}}},"WebSearchImageResult":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"The URL of the image"},"description":{"type":"string","description":"An LLM-generated description of the image. This is only available if includeImageDescriptions is set to true"}}},"WebSearchResult":{"type":"object","required":["title","url","content","score"],"properties":{"title":{"type":"string","description":"The title of the search result"},"url":{"type":"string","description":"The URL of the search result"},"content":{"type":"string","description":"The most query-related content from the scraped URL"},"score":{"type":"number","format":"double","description":"The relevance score of the search result"},"raw_content":{"type":"string","description":"The parsed and cleaned HTML content of the site. This is only available if includeRawContent is set to true"},"publishedDate":{"type":"string","description":"The publication date of the source. This is only available if the search topic is set to news"}}},"WebSearchRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"The query to run a search on"},"searchDepth":{"type":"string","enum":["basic","advanced"],"description":"The depth of the search. 'advanced' search is tailored to retrieve the most relevant sources and content snippets for your query, while 'basic' search provides generic content snippets from each source"},"topic":{"type":"string","enum":["general","news"],"description":"The category of the search. Determines which agent will be used"},"days":{"type":"integer","format":"int32","minimum":1,"maximum":365,"description":"The number of days back from the current date to include in the results. Available only when using the 'news' topic"},"timeRange":{"type":"string","enum":["day","week","month","year","d","w","m","y"],"description":"The time range back from the current date"},"maxResults":{"type":"integer","format":"int32","minimum":0,"maximum":20,"description":"The maximum number of search results to return"},"chunksPerSource":{"type":"integer","format":"int32","minimum":1,"maximum":10,"description":"Maximum number of relevant chunks returned per source. Available only when searchDepth is 'advanced'"},"includeImages":{"type":"boolean","description":"Include a list of query-related images in the response"},"includeImageDescriptions":{"type":"boolean","description":"Include a list of query-related images and their descriptions in the response"},"includeAnswer":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["basic","advanced"]}],"description":"Include an answer to the query generated by an LLM based on search results. A 'basic' (or true) answer is quick but less detailed; an 'advanced' answer is more detailed"},"includeRawContent":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["markdown","text"]}],"description":"Include the cleaned and parsed HTML content of each search result. 'markdown' or True returns search result content in markdown format. 'text' returns the plain text from the results and may increase latency"},"includeDomains":{"type":"array","items":{"type":"string"},"description":"A list of domains to specifically include in the search results"},"excludeDomains":{"type":"array","items":{"type":"string"},"description":"A list of domains to specifically exclude from the search results"},"country":{"type":"string","description":"Boost search results from a specific country. This will prioritize content from the selected country in the search results. Available only if topic is general"},"timeout":{"type":"integer","format":"int32","minimum":1,"maximum":300,"description":"A timeout to be used in requests to the Tavily API"}}}}},"paths":{"/ai/web-search":{"post":{"operationId":"AI_webSearch","summary":"AI Web Search","description":"Performs a web search using advanced AI-powered search capabilities. This endpoint leverages the Tavily API to provide comprehensive search results with optional LLM-generated answers, image results, and content extraction.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebSearchResponse"}}}}},"tags":["AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebSearchRequest"}}}}}}}} ``` # Organisation Get any informations about your organisation. ## Get your Organisation information > Retrieve your organization's profile. Useful for verifying the account authenticated ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Organisation"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"OrganisationResponse":{"type":"object","required":["_id","domain","name","created_at","updated_at"],"properties":{"_id":{"type":"integer","format":"int32","description":"Organisation ID"},"domain":{"type":"string","description":"Organisation domain"},"name":{"type":"string","description":"Organisation name"},"created_at":{"type":"string","description":"Creation timestamp"},"updated_at":{"type":"string","description":"Last update timestamp"}}}}},"paths":{"/organisation":{"get":{"operationId":"Organisation_getOrganisation","summary":"Get your Organisation information","description":"Retrieve your organization's profile. Useful for verifying the account authenticated","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganisationResponse"}}}}},"tags":["Organisation"]}}}} ``` ## Get Organisation Value Proposition > Retrieves the value proposition for your tenant, containing persona-specific value propositions ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Organisation"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"ValueProposition":{"type":"object","required":["persona","valueProp"],"properties":{"persona":{"type":"string","description":"Target persona or role"},"valueProp":{"type":"string","description":"Value proposition for this persona"}}}}},"paths":{"/organisation/value-prop":{"get":{"operationId":"Organisation_getValueProposition","summary":"Get Organisation Value Proposition","description":"Retrieves the value proposition for your tenant, containing persona-specific value propositions","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ValueProposition"}}}}}},"tags":["Organisation"]}}}} ``` # Custom Ingestion API (Coming Soon) Push your own customer & activity data into MadKudu in real time, then use it everywhere—Sales Copilot, AI Scoring, MadKudu MCP, etc. The Ingestion API allows you to send custom customer or activity data into MadKudu in real time. It’s ideal for ingesting product usage events, marketing actions, or any proprietary/purchased signals—especially when native integrations (e.g. Salesforce, HubSpot) are not an option. Whether it’s product usage from your app, marketing events from custom systems, or any proprietary or purchased signals, this API gives you a single, secure, schema-flexible way to get your data into the MadKudu pipeline.
## When to use the Ingestion API Use this API when you need to send data to MadKudu * that can’t be synced through existing native integrations (see integration list) * where going through Snowflake, BigQuery or S3 is a heavier lift If your data is already piped into Segment or your warehouse, we recommend starting with those integrations. ## Supported data objects
TypeDescription
contact eventaction or behavior (e.g. “signed_up”) tied to a person
account eventaction or behavior (e.g. “new funding round”) tied to a company
contactUpdate to person-level attributes
accountUpdate to company/account-level attributes
## How the Ingestion API works There 2 ingestion modes to choose from 1. Lightweight JSON file upload directly to the API (payloads up to 1 MB) 2. Heavyweight JSONL file uploads to a S3 URL (gzip file up to 2 GB) ## Format Each ingestion mode expects the same record format.\ Files **must** follow the schema defined in the Upload JSON Schema Reference or they will be **rejected** ## Ingestion mode 1: Lightweight JSON upload to API Use this mode for small, frequent uploads (e.g. real-time or near real-time updates). * **Payload limit**: Up to 1 MB (uncompressed) * **Content type**: `application/json` * **Upload method**: `POST` `https://madapi.madkudu.com/ingestion/upload-json` * **Recommended for**: * Testing integrations * Event-based ingestion * Low-latency use cases ## Import data via API > Directly upload contact, account, or activity data in JSON format through the API for immediate processing. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Ingestion"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"JsonUploadResponse":{"type":"object","required":["status","message","file_key"],"properties":{"status":{"type":"string","description":"Upload status"},"message":{"type":"string","description":"Upload message"},"file_key":{"type":"string","description":"Generated file key for the uploaded data"}},"description":"Response model for JSON upload"},"JsonUploadRequest":{"type":"object","required":["stream","data"],"properties":{"stream":{"allOf":[{"$ref":"#/components/schemas/AcceptedStream"}],"description":"Stream type for the data"},"data":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},{"type":"array","items":{"$ref":"#/components/schemas/Account"}},{"type":"array","items":{"$ref":"#/components/schemas/ContactEvent"}},{"type":"array","items":{"$ref":"#/components/schemas/AccountEvent"}}],"description":"Data array - contents depend on stream type"}},"description":"Request model for direct JSON upload"},"AcceptedStream":{"type":"string","enum":["account","account_event","contact","contact_event"],"description":"Accepted streams for customer data"},"Contact":{"type":"object","required":["contact_id","email","contact_properties"],"properties":{"type":{"type":"string","enum":["contact"],"description":"Type identifier for contact","default":"contact"},"contact_id":{"type":"string","description":"Unique identifier for the contact"},"email":{"type":"string","description":"Email address of the contact"},"contact_properties":{"type":"object","unevaluatedProperties":{},"description":"Additional contact properties"}},"description":"Contact model for ingestion"},"Account":{"type":"object","required":["account_id","domain","account_properties"],"properties":{"type":{"type":"string","enum":["account"],"description":"Type identifier for account","default":"account"},"account_id":{"type":"string","description":"Unique identifier for the account"},"domain":{"type":"string","description":"Domain of the account"},"account_properties":{"type":"object","unevaluatedProperties":{},"description":"Additional account properties"}},"description":"Account model for ingestion"},"ContactEvent":{"type":"object","required":["event_id","contact_id","event","event_timestamp","event_properties"],"properties":{"event_type":{"type":"string","enum":["contact_event"],"description":"Event type identifier","default":"contact_event"},"event_id":{"type":"string","description":"Unique identifier for the event"},"contact_id":{"type":"string","description":"Contact identifier for the event"},"event":{"type":"string","description":"Event name"},"event_timestamp":{"type":"string","format":"date-time","description":"Timestamp when the event occurred (ISO 8601 format)"},"event_properties":{"type":"object","unevaluatedProperties":{},"description":"Additional event properties"}},"description":"Contact event model for ingestion"},"AccountEvent":{"type":"object","required":["event_id","account_id","event","event_timestamp","event_properties"],"properties":{"event_type":{"type":"string","enum":["account_event"],"description":"Event type identifier","default":"account_event"},"event_id":{"type":"string","description":"Unique identifier for the event"},"account_id":{"type":"string","description":"Account identifier for the event"},"event":{"type":"string","description":"Event name"},"event_timestamp":{"type":"string","format":"date-time","description":"Timestamp when the event occurred (ISO 8601 format)"},"event_properties":{"type":"object","unevaluatedProperties":{},"description":"Additional event properties"}},"description":"Account event model for ingestion"}}},"paths":{"/ingestion/upload-json":{"post":{"operationId":"Ingestion_uploadJson","summary":"Import data via API","description":"Directly upload contact, account, or activity data in JSON format through the API for immediate processing.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonUploadResponse"}}}}},"tags":["Ingestion"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonUploadRequest"}}}}}}}} ``` ## Ingestion mode 2: Heavyweight JSONL file upload to S3 Use this mode for large batch uploads (e.g. daily exports or backfills). Your input file must be in **JSONL** format, then compressed using **gzip**. * **Payload limit**: Up to 2 GB (compressed as `.jsonl.gz`) * **Upload method**: 1. Request a pre-signed S3 URL from the API `POST /ingestion/request-upload-url` 2. Upload the `.jsonl.gz` file directly to the S3 URL with the command line, [AWS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html), Postman or other script Example of request ``` curl -X PUT \ -T your-file.jsonl.gz \ "https://madkudu-ingestion.s3.amazonaws.com/tmp/your-upload-id.json.gz?...[signature]" ``` 3. Get confirmation of the upload from the API `POST /ingestion/notify-upload-complete` * **Recommended for**: * Large CRM exports * Historical event backfills * Low-frequency, high-volume ingestion ## Generate Upload Url > Generate a presigned URL for file upload. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Ingestion"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"UploadResponse":{"type":"object","required":["upload_url","file_key"],"properties":{"upload_url":{"type":"string","description":"Presigned URL for file upload"},"file_key":{"type":"string","description":"Unique file key for the uploaded file"}}},"UploadRequest":{"type":"object","required":["stream","content_type","content_encoding"],"properties":{"stream":{"allOf":[{"$ref":"#/components/schemas/AcceptedStream"}],"description":"Stream type for the data"},"content_type":{"allOf":[{"$ref":"#/components/schemas/ContentType"}],"description":"Content type of the file to upload"},"content_encoding":{"allOf":[{"$ref":"#/components/schemas/ContentEncoding"}],"description":"Content encoding for the file"}}},"AcceptedStream":{"type":"string","enum":["account","account_event","contact","contact_event"],"description":"Accepted streams for customer data"},"ContentType":{"type":"string","enum":["application/jsonl"],"description":"Content types for customer data"},"ContentEncoding":{"type":"string","enum":["gzip"],"description":"Content encodings for customer data"}}},"paths":{"/ingestion/generate-upload-url":{"post":{"operationId":"Ingestion_generateUploadUrl","summary":"Generate Upload Url","description":"Generate a presigned URL for file upload.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadResponse"}}}}},"tags":["Ingestion"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadRequest"}}}}}}}} ``` ### GZIP your file and Upload it to the Upload URL Here is a Python script ```python import requests import gzip import shutil def upload_jsonl_to_s3_presigned_url(file_path, presigned_url): with open(file_path, "rb") as f: response = requests.put( presigned_url, data=f, headers={"Content-Type": "application/jsonl", "Content-Encoding": "gzip"}, ) if response.status_code == 200: print("Upload successful") else: print(f"Upload failed: {response.status_code} - {response.text}") file_path = "valid.jsonl" # Compress the file compressed_file = file_path + ".gz" with open(file_path, "rb") as f_in: with gzip.open(compressed_file, "wb") as f_out: shutil.copyfileobj(f_in, f_out) # Get presigned upload url from previous step upload_jsonl_to_s3_presigned_url(compressed_file, presigned_url) ``` ## Confirm Upload > Confirm that a file has been uploaded. ```json {"openapi":"3.1.0","info":{"title":"MadAPI","version":"0.0.0"},"tags":[{"name":"Ingestion"}],"servers":[{"url":"https://madapi.madkudu.com","description":"Production server","variables":{}},{"url":"https://madapi.wisekudu.com","description":"Staging server","variables":{}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"ConfirmUploadResponse":{"type":"object","required":["status","message"],"properties":{"status":{"type":"string","description":"Upload confirmation status"},"message":{"type":"string","description":"Confirmation message"}}},"ConfirmUploadRequest":{"type":"object","required":["file_key"],"properties":{"file_key":{"type":"string","description":"File key from the upload response"}}}}},"paths":{"/ingestion/confirm-upload":{"post":{"operationId":"Ingestion_confirmUpload","summary":"Confirm Upload","description":"Confirm that a file has been uploaded.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmUploadResponse"}}}}},"tags":["Ingestion"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmUploadRequest"}}}}}}}} ``` # Introduction This *legacy* Scoring API has a different API key and authentication than the new API, please refer to the right article ## Requests * All requests should be made using *https\://*. * All response bodies, including errors are encoded in JSON. We have official language bindings in: * [Node.js](https://github.com/MadKudu/madkudu-node) ## Rate Limiting You can make up to 600 requests per endpoint per minute. Once you reach that limit, you will start receiving errors (HTTP code 429). # Authentication The MadKudu Legacy API uses HTTP Basic Auth and requires using HTTPS on all API calls. Your API Key should be used as the basic auth username. You do not need to provide a password. For example, if your user’s API key was `ABCD1234`, you need to Base64 encode the string `ABCD1234:` (Please note the colon at the end) and prepend the string `Basic`\`. In this case, this would result in a final header of: `Authorization: Basic QUJDRDEyMzQ6` ## Ping API endpoint > Test endpoint to verify API connectivity and authentication. Returns status 'ok' if the authorization is valid. ```json {"openapi":"3.1.0","info":{"title":"MadKudu Legacy API","version":"0.0.0"},"tags":[{"name":"Utilities"}],"servers":[{"url":"https://api.madkudu.com","description":"Legacy API server","variables":{}}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"Basic"}},"schemas":{"Services.Utilities.PingResponse":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["ok"],"description":"Status of the API"}},"description":"Ping response"},"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"}}},"paths":{"/v1/ping":{"get":{"operationId":"Utilities_ping","summary":"Ping API endpoint","description":"Test endpoint to verify API connectivity and authentication. Returns status 'ok' if the authorization is valid.","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Services.Utilities.PingResponse"}}}},"401":{"description":"Access is unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Common.Errors.AuthenticationError"}}}},"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":["Utilities"]}}}} ``` # 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"}}}}}}}} ``` # 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"}}}}}}}} ``` # Job Changes ## Set job changes watch list > You can define with this endpoint which person do you want to track with the job changes features. Posting a new watch list will replace the previous one (if existing). ```json {"openapi":"3.1.0","info":{"title":"MadKudu Legacy API","version":"0.0.0"},"tags":[{"name":"Job Changes"}],"servers":[{"url":"https://api.madkudu.com","description":"Legacy API server","variables":{}}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"Basic"}},"schemas":{"Services.JobChanges.WatchListUploadResponse":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"Status of the upload"},"processed_count":{"type":"integer","format":"int32","description":"Number of emails processed"},"message":{"type":"string","description":"Upload message"}},"description":"Watch list upload response"},"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"}}},"paths":{"/v1/integrations/job_changes/watch-list/csv":{"post":{"operationId":"JobChanges_setWatchList","summary":"Set job changes watch list","description":"You can define with this endpoint which person do you want to track with the job changes features. Posting a new watch list will replace the previous one (if existing).","parameters":[],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Services.JobChanges.WatchListUploadResponse"}}}},"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":["Job Changes"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"watch_list_csv":{"description":"The csv file containing your watchlist, it should include at least one column containing the email"}},"required":["watch_list_csv"]}}},"description":"Multipart form data containing the CSV file"}}}}} ```