Mantheos Realtime Data API Documentation

Introduction

Welcome to the Mantheos API v2 documentation. This documentation provides information on how you may access the API endpoints and consume them for the development of your solutions.

The API is based on the REST framework. Please keep in mind that all requests need to be made over SSL and encoded in JSON format.

Should you have further questions, feel free to contact our tech team via support@mantheos.com.

Required Python Libraries

We will be using the requests library. Please ensure that you have it installed in your environment. 

pip install requests

Next, import the requests library to your python file. 

import requests

Authentication

To successfully consume the API you will require to pass in your API token under the Authorization header in each request. Prepend Token before the key value, as shown on the right. Should you not have an API Token yet, please contact our sales team to receive one.

Please bear in mind to also specify the Content-Type as application/json format.

Compulsory Headers for All Requests 

headers = {
    "Authorization": "Token xxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
}

Rate Limits

Each user is limited to 1 request per second, and 20,000 requests per day.

Exceeding this limit will result in a 429 (Too Many Requests) HTTP error status code.

This rate limit is endpoint agnostic, and not endpoint specific. In other words, the rate limit counter tracks the aggregated usage of all endpoints.

Response Codes

HTTP Status Codes

Our API returns standard HTTP success or error status codes as listed below.

Code Title Description
200 Success The request was successful
400 Bad Request The request data has not been provided correctly
401 Unauthorized Your API key is not authorised to access this endpoint
403 Forbidden You do not have sufficient credits. Please top-up your account.
404 Not found The endpoint does not exist
429 Too Many Requests You have exceeded the rate limits.
500 Internal Server Error An error occurred on the server. Should this error persis, please contact our technical team.
503 Service Unavailable The API is temporarily unavailable

API Status Codes

In addition to the regular HTTP response codes the API will include an api_status_code with further details as listed below.

Code Description
1001 Method Not Allowed
1002 Authentication credentials were not provided
1003 You do not have permission to perform this action
1004 Insufficient credits
1005 Request has been throttled
1006 Field input errors
1007 Processing error
1008 Include the request_id parameter in your GET request
1009 Improperly formatted parameter value
1010 Incorrect request ID, please make sure the request_id in the url parameter is correct
1011 Locations not found
1012 Universities not found
1013 Companies not found
1100 Improperly formatted parameter value
1150 Improperly formatted parameter value
1151 The submitted profile url is not valid. Please make sure to submit the full url of the profile
1152 Either linkedin_profile_url or profile_id must be included
1175 Improperly formatted parameter value
1250 Improperly formatted parameter value
1251 The submitted company url is not valid. Please make sure to submit the full url of the profile
1300 Improperly formatted parameter value
1301 The submitted post url is not valid. Please make sure to submit the full url of the post. Example: 'linkedin.com/posts/post-id/'
1302 'start' parameter is not valid. Please collect the profile activities incrementally, starting from 0, with a consistent count.
1400 Improperly formatted parameter value
1401 The inputted account does not exist
2000 Processing
2001 Profile not found or no longer available
2002 Company not found or no longer available
2003 Activity not found or no longer available
2100 Processing error
2101 Processing error
2150 Processing error
2175 Processing error
2176 profile_id not found
2200 Processing error
2250 Processing error
2275 Processing error
2276 company_id not found
2300 Processing error
2350 Processing error
2375 Processing error
2375 Processing error
2400 Processing error
2450 Processing error
3000 Request completed successfully
3001 Insufficient credits
3002 Credit deduction failed
3003 API Temporarily Unavailable
3004 API Temporarily Unavailable

Filter Codes

The filters below are used to specify your search criteria for endpoints such POST Profiles Count, POST Profiles Search and POST Companies Search.

How to Include All Options

Including All Options for Each Filter

Negative example - Do not submit all options for the various filters in a list as shown below: 

{
    "companysizes_included": [0, 1, 2, 3, 4, 5, 6, 7, 8],
    "industries_included": [0, 1, 2, 3, 4, 5, 6, 7, 8, ...],
    "senioritylevels_included": [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
    "jobfunctions_included": [0, 1, 2, 3, 4, 5, 6, 7, 8, ...],
    "num_of_followers": [0, 1, 2, 3, 4]
}

Positive example - Simply leave the filters blank - all options will be included. 

{
    "companysizes_included": [],
    "industries_included": [],
    "senioritylevels_included": [],
    "jobfunctions_included": [],
    "num_of_followers": []
}

Industries

ID Description
0 Accounting
1 Airlines/Aviation
2 Alternative Dispute Resolution
3 Alternative Medicine
4 Animation
5 Apparel & Fashion
6 Architecture & Planning
7 Arts and Crafts
8 Automotive
9 Aviation & Aerospace
10 Banking
11 Biotechnology
12 Broadcast Media
13 Building Materials
14 Business Supplies and Equipment
15 Capital Markets
16 Chemicals
17 Civic & Social Organization
18 Civil Engineering
19 Commercial Real Estate
20 Computer & Network Security
21 Computer Games
22 Computer Hardware
23 Computer Networking
24 Computer Software
25 Construction
26 Consumer Electronics
27 Consumer Goods
28 Consumer Services
29 Cosmetics
30 Dairy
31 Defense & Space
32 Design
33 Education Management
34 E-Learning
35 Electrical/Electronic Manufacturing
36 Entertainment
37 Environmental Services
38 Events Services
39 Executive Office
40 Facilities Services
41 Farming
42 Financial Services
43 Fine Art
44 Fishery
45 Food & Beverages
46 Food Production
47 Fund-Raising
48 Furniture
49 Gambling & Casinos
50 Glass, Ceramics & Concrete
51 Government Administration
52 Government Relations
53 Graphic Design
54 Health, Wellness and Fitness
55 Higher Education
56 Hospital & Health Care
57 Hospitality
58 Human Resources
59 Import and Export
60 Individual & Family Services
61 Industrial Automation
62 Information Services
63 Information Technology and Services
64 Insurance
65 International Affairs
66 International Trade and Development
67 Internet
68 Investment Banking
69 Investment Management
70 Judiciary
71 Law Enforcement
72 Law Practice
73 Legal Services
74 Legislative Office
75 Leisure, Travel & Tourism
76 Libraries
77 Logistics and Supply Chain
78 Luxury Goods & Jewelry
79 Machinery
80 Management Consulting
81 Maritime
82 Market Research
83 Marketing and Advertising
84 Mechanical or Industrial Engineering
85 Media Production
86 Medical Devices
87 Medical Practice
88 Mental Health Care
89 Military
90 Mining & Metals
91 Motion Pictures and Film
92 Museums and Institutions
93 Music
94 Nanotechnology
95 Newspapers
96 Non-Profit Organization Management
97 Oil & Energy
98 Online Media
99 Outsourcing/Offshoring
100 Package/Freight Delivery
101 Packaging and Containers
102 Paper & Forest Products
103 Performing Arts
104 Pharmaceuticals
105 Philanthropy
106 Photography
107 Plastics
108 Political Organization
109 Primary/Secondary Education
110 Printing
111 Professional Training & Coaching
112 Program Development
113 Public Policy
114 Public Relations and Communications
115 Public Safety
116 Publishing
117 Railroad Manufacture
118 Ranching
119 Real Estate
120 Recreational Facilities and Services
121 Religious Institutions
122 Renewables & Environment
123 Research
124 Restaurants
125 Retail
126 Security and Investigations
127 Semiconductors
128 Shipbuilding
129 Sporting Goods
130 Sports
131 Staffing and Recruiting
132 Supermarkets
133 Telecommunications
134 Textiles
135 Think Tanks
136 Tobacco
137 Translation and Localization
138 Transportation/Trucking/Railroad
139 Utilities
140 Venture Capital & Private Equity
141 Veterinary
142 Warehousing
143 Wholesale
144 Wine and Spirits
145 Wireless
146 Writing and Editing

Industries Filters in JSON Format 

{
    0: "Accounting",
    1: "Airlines/Aviation",
    2: "Alternative Dispute Resolution",
    3: "Alternative Medicine",
    4: "Animation",
    5: "Apparel & Fashion",
    6: "Architecture & Planning",
    7: "Arts and Crafts",
    8: "Automotive",
    9: "Aviation & Aerospace",
    10: "Banking",
    11: "Biotechnology",
    12: "Broadcast Media",
    13: "Building Materials",
    14: "Business Supplies and Equipment",
    15: "Capital Markets",
    16: "Chemicals",
    17: "Civic & Social Organization",
    18: "Civil Engineering",
    19: "Commercial Real Estate",
    20: "Computer & Network Security",
    21: "Computer Games",
    22: "Computer Hardware",
    23: "Computer Networking",
    24: "Computer Software",
    25: "Construction",
    26: "Consumer Electronics",
    27: "Consumer Goods",
    28: "Consumer Services",
    29: "Cosmetics",
    30: "Dairy",
    31: "Defense & Space",
    32: "Design",
    33: "Education Management",
    34: "E-Learning",
    35: "Electrical/Electronic Manufacturing",
    36: "Entertainment",
    37: "Environmental Services",
    38: "Events Services",
    39: "Executive Office",
    40: "Facilities Services",
    41: "Farming",
    42: "Financial Services",
    43: "Fine Art",
    44: "Fishery",
    45: "Food & Beverages",
    46: "Food Production",
    47: "Fund-Raising",
    48: "Furniture",
    49: "Gambling & Casinos",
    50: "Glass, Ceramics & Concrete",
    51: "Government Administration",
    52: "Government Relations",
    53: "Graphic Design",
    54: "Health, Wellness and Fitness",
    55: "Higher Education",
    56: "Hospital & Health Care",
    57: "Hospitality",
    58: "Human Resources",
    59: "Import and Export",
    60: "Individual & Family Services",
    61: "Industrial Automation",
    62: "Information Services",
    63: "Information Technology and Services",
    64: "Insurance",
    65: "International Affairs",
    66: "International Trade and Development",
    67: "Internet",
    68: "Investment Banking",
    69: "Investment Management",
    70: "Judiciary",
    71: "Law Enforcement",
    72: "Law Practice",
    73: "Legal Services",
    74: "Legislative Office",
    75: "Leisure, Travel & Tourism",
    76: "Libraries",
    77: "Logistics and Supply Chain",
    78: "Luxury Goods & Jewelry",
    79: "Machinery",
    80: "Management Consulting",
    81: "Maritime",
    82: "Market Research",
    83: "Marketing and Advertising",
    84: "Mechanical or Industrial Engineering",
    85: "Media Production",
    86: "Medical Devices",
    87: "Medical Practice",
    88: "Mental Health Care",
    89: "Military",
    90: "Mining & Metals",
    91: "Motion Pictures and Film",
    92: "Museums and Institutions",
    93: "Music",
    94: "Nanotechnology",
    95: "Newspapers",
    96: "Non-Profit Organization Management",
    97: "Oil & Energy",
    98: "Online Media",
    99: "Outsourcing/Offshoring",
    100: "Package/Freight Delivery",
    101: "Packaging and Containers",
    102: "Paper & Forest Products",
    103: "Performing Arts",
    104: "Pharmaceuticals",
    105: "Philanthropy",
    106: "Photography",
    107: "Plastics",
    108: "Political Organization",
    109: "Primary/Secondary Education",
    110: "Printing",
    111: "Professional Training & Coaching",
    112: "Program Development",
    113: "Public Policy",
    114: "Public Relations and Communications",
    115: "Public Safety",
    116: "Publishing",
    117: "Railroad Manufacture",
    118: "Ranching",
    119: "Real Estate",
    120: "Recreational Facilities and Services",
    121: "Religious Institutions",
    122: "Renewables & Environment",
    123: "Research",
    124: "Restaurants",
    125: "Retail",
    126: "Security and Investigations",
    127: "Semiconductors",
    128: "Shipbuilding",
    129: "Sporting Goods",
    130: "Sports",
    131: "Staffing and Recruiting",
    132: "Supermarkets",
    133: "Telecommunications",
    134: "Textiles",
    135: "Think Tanks",
    136: "Tobacco",
    137: "Translation and Localization",
    138: "Transportation/Trucking/Railroad",
    139: "Utilities",
    140: "Venture Capital & Private Equity",
    141: "Veterinary",
    142: "Warehousing",
    143: "Wholesale",
    144: "Wine and Spirits",
    145: "Wireless",
    146: "Writing and Editing"
}

Company Sizes

ID Description
0 Self-employed
1 1-10 employees
2 11-50 employees
3 51-200 employees
4 201-500 employees
5 501-1000 employees
6 1001-5000 employees
7 5001-10,000 employees
8 10,001+ employees

Company Sizes Filters in JSON Format 

{
    0: "Self-employed",
    1: "1-10 employees",
    2: "11-50 employees",
    3: "51-200 employees",
    4: "201-500 employees",
    5: "501-1000 employees",
    6: "1001-5000 employees",
    7: "5001-10,000 employees",
    8: "10,001+ employees"
}

Seniority Levels

ID Description
0 Unpaid
1 Internship/Trainee
2 Entry-level
3 Senior
4 Manager
5 Director
6 Vice President (VP)
7 Chief X Officer (CXO)
8 Partner
9 Owner

Seniority Levels Filters in JSON Format 

{
    0: "Unpaid",
    1: "Internship/Trainee",
    2: "Entry-level",
    3: "Senior",
    4: "Manager",
    5: "Director",
    6: "Vice President (VP)",
    7: "Chief X Officer (CXO)",
    8: "Partner",
    9: "Owner"
}

Job Functions

ID Description
0 Accounting
1 Administrative
2 Arts and Design
3 Business Development
4 Community & Social Services
5 Consulting
6 Education
7 Engineering
8 Entrepreneurship
9 Finance
10 Healthcare Services
11 Human Resources
12 Information Technology
13 Legal
14 Marketing
15 Media & Communications
16 Military & Protective Services
17 Operations
18 Product Management
19 Program & Product Management
20 Purchasing
21 Quality Assurance
22 Real Estate
23 Research
24 Sales
25 Support

Job Functions Filters in JSON Format 

{
    0: "Accounting",
    1: "Administrative",
    2: "Arts and Design",
    3: "Business Development",
    4: "Community & Social Services",
    5: "Consulting",
    6: "Education",
    7: "Engineering",
    8: "Entrepreneurship",
    9: "Finance",
    10: "Healthcare Services",
    11: "Human Resources",
    12: "Information Technology",
    13: "Legal",
    14: "Marketing",
    15: "Media & Communications",
    16: "Military & Protective Services",
    17: "Operations",
    18: "Product Management",
    19: "Program & Product Management",
    20: "Purchasing",
    21: "Quality Assurance",
    22: "Real Estate",
    23: "Research",
    24: "Sales",
    25: "Support"
}

Followers

ID Description
0 1-50
1 51-100
2 101-1000
3 1001-5000
4 5001+

Followers Filters in JSON Format 

{
    0: "1-50",
    1: "51-100",
    2: "101-1000",
    3: "1001-5000",
    4: "5001+"
}

Profiles API

Profiles Data

This section describes the data you can expect from each returned profile. The same profile data structure will be returned from multiple profile collection endpoints as described below. Each profile is equivalent to 1 credit.

Data points of profiles that do not exist will be returned as null.

Datapoint Description
profile_id string
Tracking ID of a profile. You may use this unique profile ID in the POST Profiles ID endpoint to always update profile's data, even if the Linkedin url of this profile has changed
collected_on string
Date on which the profile data was collected
first_name string
last_name string
headline string
summary string
industry string
location string
emails array of strings
The email is provided if it is listed in Linkedin profile's contact section, summary section or in one of the current work experiences
social_accounts object 
{
    "linkedin": {
        "username": {
            "type": "string"
        },
        "url": {
            "type": "string",
            "description": "linkedin profile url in the format: https://www.linkedin.com/in/<username>/"
        },
        "is_premium": {
            "type": "string",
            "description": "whether the profile has linkedin premium"
        },
        "num_connections": {
            "type": "string",
            "description": "number of connections on Linkedin"
        }
    },
    "twitter": {
        "username": {
            "type": "string",
            "description": "twitter profile url in the format: https://twitter.com/<username>/"
        },
        "url": {
            "type": "string"
        }
    }
}
websites array of objects 
{
    "url": {
        "type": "string"
    },
    "category": {
        "type": "string"
    }
}
work_experiences array of objects

You can request the full company details for each work experience object using the company_id field as an input to the POST Companies ID API endpoint. 

{
    "company_id": {
        "type": "string",
        "description": "if null, the object is not linked to any linkedin company"
    },
    "company_name": {
        "type": "string"
    },
    "description": {
        "type": "string"
    },
    "location": {
        "type": "string"
    },
    "started_on": {
        "year": {
            "type": "integer",
            "description": "2020, 2021, etc"
        },
        "month": {
            "type": "integer",
            "description": "1 to 12"
        }    
    },
    "ended_on": {
        "year": {
            "type": "integer",
            "description": "2020, 2021, etc"
        },
        "month": {
            "type": "integer",
            "description": "1 to 12"
        }
    }
}
education array of objects 
{
    "school_name": {
        "type": "string"
    },
    "degree": {
        "type": "string"
    },
    "fields_of_study": {
        "type": "array",
        "items": {
            "type": "string"
        }
    },
    "started_on": {
       "year": {
            "type": "integer",
            "description": "2020, 2021, etc"
        },
        "month": {
            "type": "integer",
            "description": "1 to 12"
        }
    },
    "ended_on": {
        "year": {
            "type": "integer",
            "description": "2020, 2021, etc"
        },
        "month": {
            "type": "integer",
            "description": "1 to 12"
        }
    }
}
skills array of strings
Each string is a skill.
courses_taken array of objects 
{
    "name": {
        "type": "string"
    },
    "number": {
        "type": "string"
    }
}
languages array of objects 
{
    "name": {
        "type": "string"
    },
    "proficiency": {
        "type": "string",
        "description": "elementary, limited_working, professional_working, full_professional, native_or_bilingual"
    }
}
awards array of objects 
{
    "title": {
        "type": "string"
    },
    "issuer": {
        "type": "string"
    },
    "description": {
        "type": "string"
    },
    "issued_on": {
        "year": {
            "type": "integer",
            "description": "2020, 2021, etc"
        },
        "month": {
            "type": "integer",
            "description": "1 to 12"
        }
    }
}
memberships array of objects 
{
    "name": {
        "type": "string"
    },
    "position": {
        "type": "string"
    },
    "description": {
        "type": "string"
    }
    "started_on": {
        "year": {
            "type": "integer",
            "description": "2020, 2021, etc"
        },
        "month": {
            "type": "integer",
            "description": "1 to 12"
        }
    },
    "ended_on": {
        "year": {
            "type": "integer",
            "description": "2020, 2021, etc"
        },
        "month": {
            "type": "integer",
            "description": "1 to 12"
        }
    }
}
certifications array of objects 
{
    "name": {
        "type": "string"
    },
    "authority": {
        "type": "string"
    },
    "company_id": {
        "type": "string",
        "description": "if null, the object is not linked to any linkedin company"
    },
    "license_number": {
        "type": "string"
    },
    "url": {
        "type": "string"
    },
    "started_on": {
        "year": {
            "type": "integer",
            "description": "2020, 2021, etc"
        },
        "month": {
            "type": "integer",
            "description": "1 to 12"
        }
    },
    "ended_on": {
        "year": {
            "type": "integer",
            "description": "2020, 2021, etc"
        },
        "month": {
            "type": "integer",
            "description": "1 to 12"
        }
    }
}
volunteering_experiences array of objects 
{
    "role": {
        "type": "string"
    },
    "cause": {
        "type": "string"
    },
    "description": {
        "type": "string"
    },
    "company_name": {
        "type": "string"
    },
    "company_id": {
        "type": "string",
        "description": "if null, the object is not linked to any linkedin company"
    },
    "url": {
        "type": "string"
    },
    "started_on": {
        "year": {
            "type": "integer",
            "description": "2020, 2021, etc"
        },
        "month": {
            "type": "integer",
            "description": "1 to 12"
        }
    },
    "ended_on": {
        "year": {
            "type": "integer",
            "description": "2020, 2021, etc"
        },
        "month": {
            "type": "integer",
            "description": "1 to 12"
        }
    }
}
projects array of objects 
{
    "title": {
        "type": "string"
    },
    "description": {
        "type": "string"
    },
    "url": {
        "type": "string"
    },
    "started_on": {
        "year": {
            "type": "integer",
            "description": "2020, 2021, etc"
        },
        "month": {
            "type": "integer",
            "description": "1 to 12"
        }
    },
    "ended_on": {
        "year": {
            "type": "integer",
            "description": "2020, 2021, etc"
        },
        "month": {
            "type": "integer",
            "description": "1 to 12"
        }
    }
}
publications array of objects 
{
    "name": {
        "type": "string"
    },
    "publisher": {
        "type": "string"
    },
    "description": {
        "type": "string"
    },
    "url": {
        "type": "string"
    },
    "published_on": {
        "year": {
            "type": "integer",
            "description": "2020, 2021, etc"
        },
        "month": {
            "type": "integer",
            "description": "1 to 12"
        },
        "day": {
            "type": "integer",
        }
    }
}
patents array of objects 
{
    "title": {
        "type": "string"
    },
    "pending": {
        "type": "boolean"
    },
    "description": {
        "type": "string"
    },
    "patent_number": {
        "type": "string"
    },
    "url": {
        "type": "string"
    },
    "issued_in": {
        "type": "string"
    },
    "issued_on": {
        "year": {
            "type": "integer",
            "description": "2020, 2021, etc"
        },
        "month": {
            "type": "integer",
            "description": "1 to 12"
        },
        "day": {
            "type": "integer",
        }
    }
}

Profile Datapoints in JSON Format

Below is an example of datapoints from a single profile. Data points that do not exist will be returned as null. 

 
{
    "profile_id": "1111aaaa-22bb-33cc-44dd-555555eeeeee",
    "collected_on" : "2021-01-01",
    "first_name": "John",
    "last_name": "Doe",
    "headline": "Hiring Manager at Mars",
    "summary": "Lorem, ipsum dolor sit amet.",
    "industry": "Computer Software",
    "location": "Greater Colorado Springs Area",
    "emails": [
        "dbindel@yahoo.ca", 
        "floxy@gmail.com"
    ],
    "social_accounts": {
        "linkedin": {
            "username": "johndoe",
            "url": "https://www.linkedin.com/in/johndoe/",
            "is_premium": true,
            "num_connections": "500+"
        },
        "twitter": {
            "username": "example",
            "url": "https://twitter.com/example/"
        } 
    },
    "websites": [
        {
            "url": "https://www.example.com/",
            "category": "company"
        }
    ],
    "work_experiences": [
        {
            "company_id": "1111aaaa-22bb-33cc-44dd-555555eeeeee",
            "company_name": "Mars",
            "title": "Human Resource Partner",
            "description": "Lorem, ipsum dolor sit amet.",
            "location": "Berlin Area, Germany",
            "started_on": {
                "year": 2015,
                "month": 11
            },
            "ended_on": {
                "year": 2020,
                "month": 12
            }
        }
    ],
    "education": [
        {
            "school_name": "University of Mars",
            "degree": "Bachelor of Business",
            "started_on": {
                "year": 2011,
                "month": 8
            },
            "ended_on": {
                "year": 2015,
                "month": 8
            },
            "fields_of_study": [
                "Human Resources Management"
            ]
        }
    ],
    "skills": [
        "Account Management", 
        "PowerPoint"
    ],
    "languages": [
        {
            "name": "English",
            "proficiency": "full_professional"
        }       
    ],
    "courses_taken": [
        {
            "name": "Presentation"
        },
        {
            "name": "Team work"
        }
    ],
    "awards": [
        {
            "title": "Extinguished Toastmaster",
            "description": "Lorem, ipsum dolor sit amet.",
            "issuer": "Toastmasters Club",
            "issued_on": {
                "year": 2015,
                "month": 5
            }
        }        
    ],
    "memberships": [
        {
            "name": "Toastmaster Club",
            "position": "President",
            "description": "Lorem ipsum dolor sit amet.",
            "started_on": {
                "year": 2013,
                "month": 11
            },
            "ended_on": {
                "year": 2016,
                "month": 6
            }
        }
    ],
    "certifications": [
        {
            "name": "Machine Learning in HR",
            "authority": "Harvard University",
            "company_id": "1111aaaa-22bb-33cc-44dd-555555eeeeee",
            "license_number": "123123",
            "url": "https://www.example.com/",
            "started_on": {
                "year": 2014,
                "month": 5
            },
            "ended_on": {
                "year": 2015,
                "month": 4
            }
        }
    ],
    "volunteering_experiences": [
        {
            "role": "Team Lead",
            "cause": "HUMANITARIAN_RELIEF",
            "description": "Volunteered as team lead at unicef",
            "company_name": "Mars Humanitarian",
            "company_id": "1111aaaa-22bb-33cc-44dd-555555eeeeee",
            "url": "https://www.example.com/",
            "started_on": {
                "year": 2017,
                "month": 4
            },
            "ended_on": {
                "year": 2018,
                "month": 4
            }
        }
    ],
    "projects": [
        {
            "title": "Rocket Science Project",
            "description": "Lorem ipsum dolor sit amet.",
            "url": "https://www.example.com/",
            "started_on": {
                "year": 2015,
                "month": 4
            },
            "ended_on": {
                "year": 2016,
                "month": 2
            }
        }
    ],
    "publications": [
        {
            "name": "Mars Rocket in 2200",
            "publisher": "Mars Holdings",
            "description": "Lorem ipsum dolor sit amet.",
            "url": "https://www.example.com/",
            "published_on": {
                "day": 8,
                "year": 2011,
                "month": 5
            }
        }        
    ],
    "patents": [
        {
            "title": "Rocket design to Mars",
            "pending": false,
            "issued_in": "de",
            "description": "Lorem ipsum dolor sit amet.",
            "patent_number": "123123",
            "url": "https://www.example.com/",
            "issued_on": {
                "day": 13,
                "year": 2006,
                "month": 5
            }
        }        
    ]
}

POST Profiles Search

This endpoint allows you to submit a profiles search order. Specify the search criteria based on the filter parameters below and the number of profiles you would like to collect.

Using this endpoint you are able to collect up to 2000 profiles for each specific filter combination, with up to 10 profiles in each request. Use the start and count parameters to specify which profiles you would like to collect along the spectrum of 2000 profiles. As an example if you wish to collect 35 profiles use 4 following requests:

Request # Start Count
1 0 10
2 10 10
3 20 10
4 30 5

Should you wish to collect less than 10 profiles, keep start to 0 and specify the amount of profiles that you would like to collect in the count parameter.

The GET request link is included in the response data, under the get_request_url field. More details in the Response from Profiles Search Request on the right.

HTTP Request

POST https://www.mantheos.com/api/v2/profiles/search/
Parameter Description
keywords_str string
Keywords that can be found in the whole profile.
first_name string
last_name string
locations_included array of strings
Cities or Countries. You can include multiple locations, separating them by commas.
companies_included array of strings
Company name or a Linkedin company url. You can include multiple companies, separating them by commas.
Supported input formats:
"Tuskla"
"www.linkedin.com/company/tuskla/"
"www.linkedin.com/company/23453/"
companies_included_type string
current or past. Defaults to current if unspecified.
titles_included array of strings
Job titles or keywords that a job title contains. You can include multiple job titles, separating them by commas.
titles_included_type string
current or past. Defaults to current if unspecified.
companysizes_included array of integers
Define a list of company sizes to include. Refer to the Company Sizes filters in the section above.
industries_included array of integers
Define a list of industries to include. Refer to the Industries filters in the section above.
senioritylevels_included array of integers
Define a list of seniority levels to include. Refer to the Senority Levels filters in the section above.
jobfunctions_included array of integers
Define a list of job functions to include. Refer to the Job Functions filters in the section above.
universities_included array of strings
School name or linkedin school url. You can include multiple schools, separating them by commas.
Supported input formats:
"Seal University"
"www.linkedin.com/school/walrus-university/"
start integer (required) 0 - 1999
The index of the first item you want results for.
count integer (required) 1 - 10
The number of items you want included on each page of results. There could be fewer items remaining than the value you specify.

Submit a Profiles Search Request

This example contains all parameters/filters for completeness. You may leave out filters that you are not using from the request. 

import requests

headers = {
    "Authorization": "Token xxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
}

url = "https://www.mantheos.com/api/v2/profiles/search/"

filters = {
    "keywords_str": "we are hiring",
    "first_name": "",
    "last_name": "",
    "locations_included": [
        "Germany",
        "Netherlands"
    ],
    "companies_included": [
        "visa",
        "mastercard"
    ],
    "companies_included_type": "past",
    "titles_included": [
        "hiring", 
        "talent"
    ],
    "titles_included_type": "past",
    "companysizes_included": [3, 4, 5],
    "industries_included": [20, 24, 63, 67],
    "senioritylevels_included": [4, 5],
    "jobfunctions_included": [5, 9],
    "universities_included": [
        "Seal University",
        "www.linkedin.com/school/walrus-university/"
    ],
    "start": 0,
    "count": 10
}

response = requests.post(url, headers=headers, json=filters)

Response from Profiles Search Request

The response to the POST request contains the info attribute, which includes the get_request_url. Use this value to send a GET request to collect the requested profiles. The estimated data processing time is indicated by the request_data_in attribute (in seconds). Please make sure to send the GET request after this period of time. 

{
    "info": {
        "request_id": "1111aaaa-22bb-33cc-44dd-555555eeeeee",
        "request_data_in": 15.0,
        "get_request_url": "https://www.mantheos.com/api/v2/?id=1111aaaa-22bb-33cc-44dd-555555eeeeee",
        "api_status_code": 2000,
        "credits": 100
    },
    "search_input": {
        "keywords_str": "we are hiring",
        "first_name": "",
        "last_name": "",
        "locations_included": [
            "Germany",
            "Netherlands"
        ],
        "companies_included": [
            "visa",
            "mastercard"
        ],
        "companies_included_type": "past",
        "titles_included": [
            "hiring", 
            "talent"
        ],
        "titles_included_type": "past",
        "companysizes_included": [3, 4, 5],
        "industries_included": [20, 24, 63, 67],
        "senioritylevels_included": [4, 5],
        "jobfunctions_included": [5, 9],
        "universities_included": [
            "Seal University",
            "www.linkedin.com/school/walrus-university/"
        ],
        "start": 0,
        "count": 10
    }
}

POST Profiles Linkedin Url

Search via a profile linkedin URL. This endpoint processes one profile at a time. The profile data will be provided instantly in the response of this POST request.

Please ensure that the Linkedin URL contains the basic structure: "linkedin.com/in/profile-id".

HTTP Request

POST https://www.mantheos.com/api/v2/profiles/linkedin-url/
Parameter Description
linkedin_profile_url string (required)
Full url of the profile

Submit a Profiles Linkedin URL Request 

import requests

headers = {
    "Authorization": "Token xxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
}

url = "https://www.mantheos.com/api/v2/profiles/linkedin-url/"

data = {
    "linkedin_profile_url": "www.linkedin.com/in/elon/",
}

response = requests.post(url, headers=headers, json=data)

Response from Profiles Linkedin URL Request 

{
    "info": {
        "request_id": "1111aaaa-22bb-33cc-44dd-555555eeeeee",
        "profiles_found": 1,
        "api_status_code": 3000,
        "credits_charged": 1,
        "credits": 99,
    },
    "search_input": {
        {"search input data as listed above"}
    },
    "profiles": [
        {"profiles data as listed above"}
    ]
}

POST Profiles ID

Search via profile ID. This endpoint processes one profile at a time. The profile data will be provided instantly in the response of this POST request.

Profile IDs are included in profile data that we provide. These IDs allow you to query for the same profile, regardless of whether they have changed their linkedin profile url.

HTTP Request

POST https://www.mantheos.com/api/v2/profiles/id/
Parameter Description
profile_id string (required)
ID of the profile

Submit a Profiles ID Request 

import requests

headers = {
    "Authorization": "Token xxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
}

url = "https://www.mantheos.com/api/v2/profiles/id/"

data = {
    "profile_id": "1111aaaa-22bb-33cc-44dd-555555eeeeee",
}

response = requests.post(url, headers=headers, json=data)

Response from Profiles ID Request 

{
    "info": {
        "request_id": "1111aaaa-22bb-33cc-44dd-555555eeeeee",
        "profiles_found": 1,
        "api_status_code": 3000,
        "credits_charged": 1,
        "credits": 99,
    },
    "search_input": {
        {"search input data as listed above"}
    },
    "profiles": [
        {"profiles data as listed above"}
    ]
}

Companies API

Companies Data

This section describes the data you can expect from each returned company profile. The same company profile data structure will be returned from multiple collection endpoints as described below. Each company profile is equivalent to 2 credits.

Data points of company profiles that do not exist will be returned as null.

Datapoint Description
company_id string
Tracking ID of a company profile. You may use this unique company ID in the POST Companies ID endpoint to always update companie's data, even if the Linkedin url of this profile has changed
collected_on string
Date on which the company data was collected
name string
location string
industry string
company_size string
employee_count integer
Number of employees on Linkedin
description string
founded integer
Year in which the company has been founded
website string
company_type string
Privately Held, Public, etc
headquarters_address object 
{
    "city": {
        "type": "string"
    },
    "line1": {
        "type": "string"
    },
    "line2": {
        "type": "string"
    },
    "country": {
        "type": "string"
    },
    "postal_code": {
        "type": "string"
    },
    "geographic_area": {
        "type": "string"
    }
}
linkedin_company_url string
specialties array of strings

Companies Datapoints in JSON Format

Below is an example of datapoints from a single company. 

{
    "company_id": "1111aaaa-22bb-33cc-44dd-555555eeeeee",
    "collected_on" : "2021-01-01",
    "name": "Tuskla",
    "location": "Cupertino, California, United States",
    "industry": "Electrical/Electronic Manufacturing",
    "company_size": "2-10",
    "employee_count": 7,
    "description": "Lorem ipsum dolor sit amet.",
    "founded": 2018,
    "website": "https://www.example.com",
    "company_type": "Privately Held",
    "headquarters_address": {
        "city": "Cupertino",
        "line1": "1 Tuskla Park Way",
        "line2": null,
        "country": "United States",
        "postal_code": "000000",
        "geographic_area": "California"
    },
    "linkedin_company_url": "https://www.linkedin.com/company/tuskla/",
    "specialties": [
        "artificial intelligence",
        "automobiles"
    ]
}

POST Companies Search

This endpoint allows you to submit a companies search order. Specify the search criteria based on the filter parameters below and the number of companies you would like to collect.

Using this endpoint you are able to collect up to 1500 companies for each specific filter combination, with up to 10 companies in each request. Use the start and count parameters to specify which companies you would like to collect along the spectrum of 1500 companies. As an example if you wish to collect 35 companies use 4 following requests:

Request # Start Count
1 0 10
2 10 10
3 20 10
4 30 5

Should you wish to collect less than 10 companies, keep start to 0 and specify the amount of companies that you would like to collect in the count parameter.

The GET request link is included in the response data, under the get_request_url field. More details in the Response from Companies Search Request on the right.

HTTP Request

POST https://www.mantheos.com/api/v2/companies/search/
Parameter Description
include_secondary_locations boolean
None
keywords_str string
Keywords that can be found in the whole company page.
locations_included array of strings
Cities or Countries. You can include multiple locations, separating them by commas.
companysizes_included array of integers
Define a list of company sizes to include. Refer to the Company Sizes filters in the section above.
industries_included array of integers
Define a list of industries to include. Refer to the Industries filters in the section above.
num_of_followers array of integers
Define a list of number of follower ranges to include. Refer to the Followers filters in the section above.
start integer (required) 0 - 1499
The index of the first item you want results for.
count integer (required) 1 - 10
The number of items you want included on each page of results. There could be fewer items remaining than the value you specify.

Submit a Companies Search Request

This example contains all parameters/filters for completeness. You may leave out filters that you are not using from the request. 

import requests

headers = {
    "Authorization": "Token xxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
}

url = "https://www.mantheos.com/api/v2/companies/search/"

filters = {
    "keywords_str": "Travel",
    "locations_included": [
        "Germany",
        "Brazil"
    ],
    "companysizes_included": [3, 4, 5],
    "industries_included": [20, 24, 63, 67],
    "num_of_followers": [0, 1, 2],
    "start": 0,
    "count": 10
}

response = requests.post(url, headers=headers, json=filters)

Response from Companies Search Request

The response to the POST request contains the info attribute, which includes the get_request_url. Use this value to send a GET request to collect the requested companies. The estimated data processing time is indicated by the request_data_in attribute (in seconds). Please make sure to send the GET request after this period of time. 

{
    "info": {
        "request_id": "1111aaaa-22bb-33cc-44dd-555555eeeeee",
        "request_data_in": 15.0,
        "get_request_url": "https://www.mantheos.com/api/v2/?id=1111aaaa-22bb-33cc-44dd-555555eeeeee",
        "api_status_code": 2000,
        "credits": 100
    },
    "search_input": {
        "keywords_str": "Travel",
        "locations_included": [
            "Germany",
            "Brazil"
        ],
        "companysizes_included": [3, 4, 5],
        "industries_included": [20, 24, 63, 67],
        "num_of_followers": [0, 1, 2],
        "start": 0,
        "count": 10
    }
}

POST Companies Linkedin URL

Search via a company linkedin url. Please ensure that the provided profile URL contains the basic structure: "linkedin.com/company/company-id".

This endpoint processes one company at a time. The profile data will be provided instantly in the response of this POST request.

HTTP Request

POST https://www.mantheos.com/api/v2/companies/linkedin-url/
Parameter Description
include_secondary_locations boolean
None
linkedin_company_url string (required)
Full url of the company

Submit a Companies Linkedin URL Request 

import requests

headers = {
    "Authorization": "Token xxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
}

url = "https://www.mantheos.com/api/v2/companies/linkedin-url/"

data = {
    "linkedin_company_url": "www.linkedin.com/company/tuskla/"
}

response = requests.post(url, headers=headers, json=data)

Response from Companies Linkedin URL Request 

{
    "info": {
        "request_id": "1111aaaa-22bb-33cc-44dd-555555eeeeee",
        "companies_found": 1,
        "api_status_code": 3000,
        "credits_charged": 2,
        "credits": 98
    },
    "search_input": {
        {"search input data as listed above"}
    },
    "companies": [
        {"companies data as listed above"}
    ]
}

POST Companies ID

Search via a comapny ID. This endpoint processes one company at a time. The profile data will be provided instantly in the response of this POST request.

HTTP Request

POST https://www.mantheos.com/api/v2/companies/id/
Parameter Description
include_secondary_locations boolean
None
company_id string (required)
ID of the company

Submit a Companies ID Request 

import requests

headers = {
    "Authorization": "Token xxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json"
}

url = "https://www.mantheos.com/api/v2/companies/id/"

data = {
    "company_id": "1111aaaa-22bb-33cc-44dd-555555eeeeee"
}

response = requests.post(url, headers=headers, json=data)

Response from Companies ID Request 

{
    "info": {
        "request_id": "1111aaaa-22bb-33cc-44dd-555555eeeeee",
        "companies_found": 1,
        "api_status_code": 3000,
        "credits_charged": 2,
        "credits": 98
    },
    "search_input": {
        {"search input data as listed above"}
    },
    "companies": [
        {"companies data as listed above"}
    ]
}