Mantheos | The Ultimate People Intelligence Tool

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"
}

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
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
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
2000	Processing
2100	Processing error
2150	Processing error
2175	Processing error
2176	`profile_id` not found
2250	Processing error
2275	Processing error
2276	`company_id` not found
3000	Request completed successfully
3001	Insufficient credits
3002	Credit deduction failed
3003	API Temporarily Unavailable

Filter Codes

The filters below are used to specify your search criteria for endpoints such as POST Profiles Search or POST Companies Search.

How to Include All Options

If you would like to include all of the options in any of the filter codes below, simply leave the filter blank. Example on the right.

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.

Please be aware if some data points of profiles do not exist, these 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" }, "description": { "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 100 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 350 profiles use 4 following requests:

Request #	Start	Count
1	0	100
2	100	100
3	200	100
4	300	50

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

After submitting the POST request, some time is required for the data to be collected and processed. The response data includes a request_data_in field. This is an estimation of how long you should wait in seconds before using the GET Profiles Search API endpoint to collect the data.

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` Linkedin school url. You can include multiple schools, separating them by commas. Supported input formats: `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 - 100` 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": [
        "www.linkedin.com/school/walrus-university/",
        "www.linkedin.com/school/seal-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],
        "start": 0,
        "count": 10
    }
}

GET Profiles Search

Collect the processed data by specifying the request_id that you have received from POST Profiles Search above.

HTTP Request


                    GET https://www.mantheos.com/api/v2/?id={request_id}

Collect Profiles Search Data

import requests

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

url = "https://www.mantheos.com/api/v2/?id=1111aaaa-22bb-33cc-44dd-555555eeeeee"

response = requests.get(url, headers=headers)

Response from Collect Profiles Search Request

{
    "info": {
        "profiles_found": 10,
        "api_status_code": 3000,
        "credits_charged": 10,
        "credits": 90,
    },
    "search_input": {
        {"search filters as listed above"}
    },
    "profiles": [
        {"profiles data as listed above"}
    ]
}

POST Profiles Linkedin Url

Search via 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 of "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": {
        "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": {
        "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.

Please be aware if some data points of company profiles do not exist, these 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`

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/",
}

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 100 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 350 companies use 4 following requests:

Request #	Start	Count
1	0	100
2	100	100
3	200	100
4	300	50

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

After submitting the POST request, some time is required for the data to be collected and processed. The response data includes a request_data_in field. This is an estimation of how long you should wait in seconds before using the GET Companies Search API endpoint to collect the data.

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
`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 - 100` 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
    }
}

GET Companies Search

Collect the processed data by specifying the request_id that you have received from POST Companies Search above.

HTTP Request


                    GET https://www.mantheos.com/api/v2/?id={request_id}

Collect Companies Search Data

import requests

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

url = "https://www.mantheos.com/api/v2/?id=1111aaaa-22bb-33cc-44dd-555555eeeeee"

response = requests.get(url, headers=headers)

Response from Collect Companies Search Request

{
    "info": {
        "companies_found": 10,
        "api_status_code": 3000,
        "credits_charged": 20,
        "credits": 80
    },
    "search_input": {
        {"search filters as listed above"}
    },
    "companies": [
        {"companies data as listed above"}
    ]
}

POST Companies Linkedin URL

Search via the provided Linkedin URL of the company. Please ensure that the provided profile URL contains at least the basic structure as "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
`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": {
        "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 the provided ID of the company.

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
`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": {
        "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"}
    ]
}

Introduction

Required Python Libraries

Authentication

Compulsory Headers for All Requests

Response Codes

HTTP Status Codes

API Status Codes

Filter Codes

How to Include All Options

Including All Options for Each Filter

Industries

Industries Filters in JSON Format

Company Sizes

Company Sizes Filters in JSON Format

Seniority Levels

Seniority Levels Filters in JSON Format

Job Functions

Job Functions Filters in JSON Format

Followers

Followers Filters in JSON Format

Profiles API

Profiles Data

Profile Datapoints in JSON Format

POST Profiles Search

HTTP Request

Submit a Profiles Search Request

Response from Profiles Search Request

GET Profiles Search

HTTP Request

Collect Profiles Search Data

Response from Collect Profiles Search Request

POST Profiles Linkedin Url

HTTP Request

Submit a Profiles Linkedin URL Request

Response from Profiles Linkedin URL Request

POST Profiles ID

HTTP Request

Submit a Profiles ID Request

Response from Profiles ID Request

Companies API

Companies Data

Companies Datapoints in JSON Format

POST Companies Search

HTTP Request

Submit a Companies Search Request

Response from Companies Search Request

GET Companies Search

HTTP Request

Collect Companies Search Data

Response from Collect Companies Search Request

POST Companies Linkedin URL

HTTP Request

Submit a Companies Linkedin URL Request

Response from Companies Linkedin URL Request

POST Companies ID

HTTP Request

Submit a Companies ID Request

Response from Companies ID Request