NAV Navbar
Logo
Shell Node.js

Introduction

Welcome to the MadKudu API.

We have official language bindings in:

You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

# With shell, you can just pass the correct header with each request
curl "https://api.madkudu.com/v1/ping" \
  -H "Authorization: Basic QUJDRDEyMzQ6"
# Make sure to replace `QUJDRDEyMzQ6` with the correct value.
const madkudu = require('@madkudu/madkudu-node')('your_api_key');

The MadKudu 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

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).

Demographics API

Companies

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.).

curl "https://api.madkudu.com/v1/companies?domain=madkudu.com" \
  -H "Authorization: Basic QUJDRDEyMzQ6"
madkudu.company.find({ domain: 'madkudu.com' })
    .then(function (company) {
        console.log(company);
    });
});
{
    "object_type": "company",
    "domain": "madkudu.com",
    "properties": {
        "name": "MadKudu",
        "domain": "madkudu.com",
        "location": {
            "state": "California",
            "state_code": "CA",
            "country": "United States",
            "country_code": "US",
            "tags": [
                "english_speaking",
                "high_gdp_per_capita"
            ]
        },
        "number_of_employees": 10,
        "industry": "Internet Software & Services",
        "customer_fit": {
            "segment": "good",
            "score": 37,
            "top_signals": [
                {
                    "name": "employee count",
                    "value": 10,
                    "type": "negative"
                },
                {
                    "name": "based in a country where gdp per capita",
                    "value": "high",
                    "type": "positive"
                },
                {
                    "name": "capital raised",
                    "value": 1370000,
                    "type": "positive"
                },
                {
                    "name": "belongs to industry where revenue per employee",
                    "value": "high",
                    "type": "positive"
                },
                {
                    "name": "number of tech found on website",
                    "value": 10,
                    "type": "positive"
                },
                {
                    "name": "web traffic volume",
                    "value": "low",
                    "type": "negative"
                }
            ]
        }
    }
}

HTTP Request

GET https://api.madkudu.com/v1/companies?domain=:domain

Query Parameters

Parameter Description
domain string (required)

Company properties

Attribute Type Description
properties.name string The name of the company associated with this person
properties.domain string The domain of the company associated with this person
properties.location object The location of the company’s headquarters.
properties.location.state string The headquarters’ state name
properties.location.state_code string The headquarters’ two-character state code
properties.location.country string The headquarters’s country
properties.location.country_code string The headquarters’s two-character country code
properties.location.tags array An array of tags describing the location
properties.number_of_employees number The number of employees at the company
properties.industry string The industry of the company

Companies (with payload)

This API endpoint is similar to the one above but it lets you provide your own enriched company data.

{
    "object_type": "company",
    "domain": "madkudu.com",
    "properties": {
        "name": "MadKudu",
        "domain": "madkudu.com",
        "location": {
            "state": "California",
            "state_code": "CA",
            "country": "United States",
            "country_code": "US",
            "tags": [
                "english_speaking",
                "high_gdp_per_capita"
            ]
        },
        "number_of_employees": 10,
        "industry": "Internet Software & Services",
        "customer_fit": {
            "segment": "good",
            "score": 37,
            "top_signals": [
                {
                    "name": "employee count",
                    "value": 10,
                    "type": "negative"
                },
                {
                    "name": "based in a country where gdp per capita",
                    "value": "high",
                    "type": "positive"
                },
                {
                    "name": "capital raised",
                    "value": 1370000,
                    "type": "positive"
                },
                {
                    "name": "belongs to industry where revenue per employee",
                    "value": "high",
                    "type": "positive"
                },
                {
                    "name": "number of tech found on website",
                    "value": 10,
                    "type": "positive"
                },
                {
                    "name": "web traffic volume",
                    "value": "low",
                    "type": "negative"
                }
            ]
        }
    }
}

HTTP Request

POST https://api.madkudu.com/v1/companies

Query Parameters

Parameter Description
domain string (required)
company object (required)

Properties

See Company properties

Persons

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.).

curl "https://api.madkudu.com/v1/persons?email=paul@madkudu.com" \
  -H "Authorization: Basic QUJDRDEyMzQ6"
madkudu.person.find({ email: 'paul@madkudu.com' })
    .then(function (person) {
        console.log(person);
    });
});
{
  "object_type": "person",
  "email": "paul@madkudu.com",
  "properties": {
    "first_name": "Paul",
    "last_name": "Cothenet",
    "domain": "madkudu.com",
    "is_student": false,
    "is_spam": false,
    "is_personal_email": false,
    "customer_fit": {
      "segment": "good",
      "score": 200,
      "top_signals": [
        { "name": "Employees count", "value": "200", "type": "positive"},
        { "name": "Software industry", "value": true, "type": "positive"}
      ]
    }
  },
  "company": {
    "properties": {
      "name": "MadKudu Inc",
      "domain": "madkudu.com",
      "location": {
        "state": "California",
        "state_code": "CA",
        "country": "United States",
        "country_code": "US",
        "tags": ["english_speaking", "high_gdp_per_capita"]      
      },
      "number_of_employees": 17000,
      "industry": "Software"             
    }
  }
}

HTTP Request

GET https://api.madkudu.com/v1/persons?email=:email

Query Parameters

Parameter Description
email string (required)

Person properties

Attribute Type Description
properties.first_name string First name of the person
properties.last_name string Last name of the the person
properties.domain string The domain associated with this email address
properties.is_student boolean true if the email is identified as a student email
properties.is_spam boolean true if the email is identified as a spam email
properties.is_personal_email boolean true if the email is identified as a personal (or disposable) email address (e.g. gmail.com)
properties.customer_fit.segment string How close is this customer from your ideal customer profile?
properties.customer_fit.top_signals array An array of signals explaining the customer_fit segment

Company properties

See Company properties

Persons (with payload)

This API endpoint is similar to the one above but it lets you provide your own enriched person data.

{
  "object_type": "person",
  "email": "paul@madkudu.com",
  "properties": {
    "first_name": "Paul",
    "last_name": "Cothenet",
    "domain": "madkudu.com",
    "is_student": false,
    "is_spam": false,
    "is_personal_email": false,
    "customer_fit": {
      "segment": "good",
      "score": 200,
      "top_signals": [
        { "name": "Employees count", "value": "200", "type": "positive"},
        { "name": "Software industry", "value": true, "type": "positive"}
      ]
    }
  },
  "company": {
    "properties": {
      "name": "MadKudu Inc",
      "domain": "madkudu.com",
      "location": {
        "state": "California",
        "state_code": "CA",
        "country": "United States",
        "country_code": "US",
        "tags": ["english_speaking", "high_gdp_per_capita"]      
      },
      "number_of_employees": 17000,
      "industry": "Software"             
    }
  }
}

HTTP Request

POST https://api.madkudu.com/v1/persons

Query Parameters

Parameter Description
email string (required)
person object (required)
company object (required)

Properties

See Person properties

Models API

Our Models API takes the model ID, and either returns the configuration value or make changes to the model configuration. It is a good method to manage MadKudu’s different prediction models in a way that would help sales and marketing teams increase conversions.

List Models

You can obtain a list of available models that have already been set up on the platform, and its configuration. To use the Models API, simply input the right request which, in this case, is just your API key.

Key in your MadKudu API key under Authorization:

curl "https://api.madkudu.com/v1/models" \
  -H "Authorization: Basic QUJDRDEyMzQ6"

The API response will look like this if you only have one model saved:

{
    "id": "BJ_sP3gsG",
    "version": "2.0",
    "type": "topical",
    "name": "find_industry",
    "config": {
        "topics": [
                    {
                    "keywords": [
                        {
                            "weight": 1,
                            "phrase": "online"
                        }
                    ],
                    "name": "e-commerce"
                },
                {
                    "keywords": [
                        {
                            "weight": 1,
                            "phrase": "location"
                        }
                    ],
                    "name": "physical_store"
                }
            ],
        "confidence_mapping": [
            {
                "score": 0,
                "confidence": 0

            },
            {
                "score": 30,
                "confidence": 50
            },
            {
                "score": 60,
                "confidence": 100
            }
        ]
    }
}

HTTP Request

GET https://api.madkudu.com/v1/models

Get a Model Definition

Sometimes you’ll want to look up the configuration value of a specific model that you’ve created and saved. The Models API returns the details of the model configuration such as keywords, phrases and weights as well as its settings for confidence_mapping.

The API response will look like this:

{
    "id": "BJ_sP3gsG",
    "version": "2.0",
    "type": "topical",
    "name": "find_industry",
    "config": {
        "topics": [
            {
                "keywords": [
                    {
                        "weight": 1,
                        "phrase": "online"
                    },
                    {
                        "weight": 0.5,
                        "phrase": "delivery"
                    }
                ],
                "name": "e-commerce"
            },
            {
                "keywords": [
                    {
                        "weight": 1,
                        "phrase": "location"
                    }
                ],
                "name": "physical_store"
            }
        ],
        "confidence_mapping": [
            {
                "score": 0,
                "confidence": 0
            },
            {
                "score": 30,
                "confidence": 50
            },
            {
                "score": 60,
                "confidence": 100
            }
        ]
    }
}

HTTP Request

GET https://api.madkudu.com/v1/models/:id

Query Parameters

The following parameters are supported in the URL query:

Parameter Type Description
id string (required) ID of the model you would like to see the definition for

Configure a New Model

To create a new model, use POST with the configurations made from platform itself so send us the parameters that should be included in the configuration such as “type”, “config” and “confidence_mapping” in the request body.

For each topic created, you can input different keywords with weights. In this case, weight directly impacts the importance of the keyword in the model. If the keyword appears on the lead’s website page two times, that will be counted as two “counts” (see Predictions API). We will then calculate the weighted score for each topic based on: keyword_n(number of counts x weight). Then, we will compute the overall score for each topic based on: sum of weighted scores for each keyword. This score will be mapped to confidence using the settings you’ve configured in confidence_mapping. Confidence ranges from 0 to 100.

Example of a request body:

{
    "type": "topical",
    "name": "find_industry",
    "version": "2.0",
    "config": {
        "topics": [
                    {
                    "keywords": [
                        {
                            "weight": 1,
                            "phrase": "online"
                        },
                         {
                            "weight": 0.5,
                            "phrase": "delivery"
                        }
                    ],
                    "name": "e-commerce"
                },
                {
                    "keywords": [
                        {
                            "weight": 1,
                            "phrase": "location"
                        }
                    ],
                    "name": "physical_store"
                }
            ],
        "confidence_mapping": [
            {
                "score": 0,
                "confidence": 0

            },
            {
                "score": 30,
                "confidence": 50
            },
            {
                "score": 60,
                "confidence": 100
            }
        ]
    }
}

HTTP Request

POST https://api.madkudu.com/v1/models/

Body Parameters

The following parameters are supported in the request body:

Parameter Type Description
type string (required) For topical models, type should be “topical”
name string (optional) Good to include a name for ease of identifying the models you created but if not included, there will not be a name object for the model created
version string (optional) If not included, it will default to 1.0
config object (required) Keyword names and phrases with their respective weights
confidence_mapping object (required) Required to obtain predictions in Predictions API

The API response will look like this (the topics and confidence_mapping object will reflect what you’ve entered in the request body):

{
    "id": "BJ_sP3gsG",
    "version": "2.0",
    "type": "topical",
    "name": "find_industry",
    "config": {
        "topics": [
        ],
        "confidence_mapping": [
        ]
    }
}

Update a Model

Sometimes you’ll need to update your model with more relevant keywords or accurate weightage allocation. This update will be done for a specific model by calling a required parameter: “id”. Simply send us the model ID and it will directly update the model with the user-specified configurations.

The metadata of the request body and API response will look the same as when you configure a new model

HTTP Request

PUT https://api.madkudu.com/v1/models/:id

Query Parameters

The following parameters are supported in the URL query:

Parameter Type Description
id string (required) ID of the model you would like to update

Body Parameters

The following parameters are supported in the request body:

Parameter Type Description
type string (required) For topical models, type should be “topical”
name string (optional) If not included, it will remain the same as what it is upon creation
version string (optional) If not included, it will remain the same as the version number upon creation
config object (required) Keyword names and phrases with their respective weights
confidence_mapping object (required) Required to obtain predictions in Predictions API

Delete a Model

Sometimes you’ll need to delete a model you’ve saved previously.

HTTP Request

DELETE https://api.madkudu.com/v1/models/:id

Query Parameters

The following parameters are supported in the URL query:

Parameter Type Description
id string (required) ID of the model you would like to delete

Predictions API

The Predictions API takes a model ID and provides predictive recommendations according to the model type.

Obtain Predictions for a Stored Model

To obtain predictions of a stored model for a specific domain, send us the “id”, “domain” and “type” parameters in the request body. The default response will only show confidence. However, you can choose to see both confidence and score by adding “show_scores” parameter in the request body.

The API response will look like this if there is a match on all topics:

{
    "domain": "lazada.com",
    "main_topic": {
        "name": "e-commerce",
        "confidence": 7
    },
    "topics": [
        {
            "name": "e-commerce",
            "confidence": 7,
            "hits": [
                {
                    "phrase": "online",
                    "count": 1
                },
                {
                    "phrase": "delivery",
                    "count": 2
                }
            ]
        },
        {
            "name": "physical_store",
            "confidence": 0
        }
    ]
}

The API response will look like this if there is no match on all topics:

{
    "domain": "carlsjr.com",
    "topics": [
        {
            "name": "e-commerce",
            "confidence": 0
        },
        {
            "name": "physical_store",
            "confidence": 0
        }
    ]
}

HTTP Request

POST https://api.madkudu.com/v1/models/:id/predictions

Query Parameters

The following parameters are supported in the URL query:

Parameter Type Description
id string (required) ID of the model you would like to obtain predictions for

Body Parameters

The following parameters are supported in the request body:

Parameter Type Description
domain string (required) Domain name of the lead you would like to obtain predictions for with the following convention: “domain.com”
show_scores string (optional) If you would like to show scores, enter “true” here, but if not included, show_scores functionality will be turned off by default

Default Response for No-Match Leads

There are times when you enter a domain, and the domain does not match any of the topics you entered. This will automatically remove the “main_topic” and “hits” array in the API response since the “confidence” and “count” value is ‘0’.

Obtain On-the-Fly Predictions

You may sometimes need to get results on the fly while creating the model. For this, you do not have to send us the model ID. You simply have to include the “type”, “topics” and “confidence_mapping” parameters required for model configuration, as well as the domain you would like to obtain predictions for. The syntax of the request may be slightly different as seen in the example request body. Again, you can choose to see both confidence and score by adding the “show_scores” parameter in the request body.

Example of a request body:

{
  "domain": "patagonia.com.au",
  "type": "topical",
  "topics":[
    {
      "topic": "has_store",
      "keywords": [{
         "phrase": "store",
         "weight": 0.25
        }, {
         "phrase": "locate",
         "weight": 1
        }, {
         "phrase": "branch",
         "weight": 1
        }, {
          "phrase": "location",
          "weight": 1
        }]}, {
        "topic": "has_stockist",
        "keywords": [{
         "phrase": "stockist",
         "weight": 1
        }, {
         "phrase": "stockists",
         "weight": 1
        }, {
         "phrase": "distributor",
         "weight": 0.5
        }
      ]
    }
  ],
  "confidence_mapping": [
            {
                "score": 0,
                "confidence": 0

            },
            {
                "score": 30,
                "confidence": 50
            },
            {
                "score": 60,
                "confidence": 100
            }
        ]
}

HTTP Request

POST https://api.madkudu.com/v1/predictions

Body Parameters

The following parameters are supported in the request body:

Parameter Type Description
domain string (required) Domain name of the lead you would like to obtain predictions for with the following convention: “domain.com”
type string (required) For topical models, type should be “topical”
topics object (required) Keyword names and phrases with their respective weights
confidence_mapping object (required) Required to obtain predictions in Predictions API
show_scores string (optional) If you would like to show scores, enter “true” here, but if not included, show_scores functionality will be turned off by default

Deprecated

Predict

curl "https://api.madkudu.com/v1/predict" \
  -H "Authorization: Basic QUJDRDEyMzQ6" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"email": "elon@tesla.com"}'

The API response will look like this:

{
  "predictions": {
    "customer_fit": {
      "segment": "very good"
    }
  }
}

where segment can be “low”, “medium”, “good”, “very good” or “not enough information”

Returns the prediction results for a given email / domain

HTTP Request

POST https://api.madkudu.com/v1/predict

Query Parameters

Parameter Description
email string (required)
domain string (required)
company object
person object

You can use either one of email or domain (if you supply both, we use email).

Additionally, if you already get them, you can pass the Clearbit company or person directly (see example on the right)

Example of body if you already have the company and person information:

{
    "email": "jane.killian@oracle.com",
    "domain": "oracle.com",
    "company": {},
    "person": {}
}

where company and person are the JSON responses from the Clearbit API.

Utilities

Ping

curl "https://api.madkudu.com/v1/ping"
  -H "Authorization: Basic QUJDRDEyMzQ6"

If the authorization is valid, the API will return:

{
  "status": "ok"
}