Demographics Person API

Lookup person by email

get

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

Authorizations

Query parameters

emailstringRequired

The email of the lead you would like to retrieve

Responses

200

The request has succeeded.

application/json

400

The server could not understand the request due to invalid syntax.

application/json

401

Access is unauthorized.

application/json

404

The server cannot find the requested resource.

application/json

429

Client error

application/json

500

Server error

application/json

get

HTTPcURLJavaScriptPython

GET /v1/persons HTTP/1.1
Host: api.madkudu.com
Authorization: Basic YOUR_SECRET_TOKEN
Accept: */*

{
  "object_type": "person",
  "email": "[email protected]",
  "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": 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"
        }
      ],
      "top_signals_formated": "↑ based in a country where gdp per capita is high\n↑ capital raised is 1,370,000\n↑ belongs to industry where revenue per employee is high\n↑ number of tech found on website is 10\n✖ employee count is 10\n✖ web traffic volume is low"
    },
    "predicted_value": 327.4
  },
  "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",
      "predicted_value": 327.4
    }
  }
}

Lookup person with enriched payload

post

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.

Authorizations

Body

Person lookup with payload request

emailstringRequired

Person email

personall ofRequired

Clearbit person payload

companyall ofRequired

Clearbit company payload

Responses

200

The request has succeeded.

application/json

400

The server could not understand the request due to invalid syntax.

application/json

401

Access is unauthorized.

application/json

422

Client error

application/json

429

Client error

application/json

500

Server error

application/json

post

HTTPcURLJavaScriptPython

POST /v1/persons HTTP/1.1
Host: api.madkudu.com
Authorization: Basic YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 568

{
  "email": "[email protected]",
  "person": {
    "id": "dcf17bf2-1598-4433-92ef-320201e2190a",
    "name": {
      "fullName": "Maxime Gaudin",
      "givenName": "Maxime",
      "familyName": "Gaudin"
    },
    "email": "[email protected]",
    "gender": "male",
    "location": "Mountain View, CA, US",
    "employment": {
      "domain": "madkudu.com",
      "name": "MadKudu",
      "title": "student",
      "role": "engineering",
      "seniority": "executive"
    }
  },
  "company": {
    "id": "a996c075-7bf1-4324-ad26-e59e97ba4fd2",
    "name": "MadKudu",
    "legalName": "MadKudu, Inc.",
    "domain": "madkudu.com",
    "metrics": {
      "employees": 10,
      "employeesRange": "1-10",
      "raised": 1370001
    }
  }
}

{
  "object_type": "person",
  "email": "[email protected]",
  "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": 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"
        }
      ],
      "top_signals_formated": "↑ based in a country where gdp per capita is high\n↑ capital raised is 1,370,000\n↑ belongs to industry where revenue per employee is high\n↑ number of tech found on website is 10\n✖ employee count is 10\n✖ web traffic volume is low"
    },
    "predicted_value": 327.4
  },
  "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",
      "predicted_value": 327.4
    }
  }
}