openapi: 3.1.0
info:
title: MadAPI
version: 0.0.0
servers:
- url: https://madapi.madkudu.com
description: Production server
variables: {}
- url: https://madapi.wisekudu.com
description: Staging server
variables: {}
security:
- ApiKeyAuth: []
tags:
- name: Lookup
- name: Accounts
- name: Persons
- name: Enrichment
- name: Search
- name: Sourcing
- name: AI
- name: Organisation
- name: Ingestion
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/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
/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
/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'
/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
/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
/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/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/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:
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/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
/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'
/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/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:
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
/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
/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/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'
/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'
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
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.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.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.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.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.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.SortingPar
# --- truncated at 32 KB (92 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/madkudu/refs/heads/main/openapi/madkudu-madapi-openapi.yml