--- updatedAt: 2025-05-15T20:37:06.000Z agentTools: projectIndex: https://docs.beauhurst.com/llms.txt --- # Get data on a list of people Use a collection ID, a list of Beauhurst People IDs or search by email to get information on the people you want # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Beauhurst API", "description": "

Usage

The API only accepts GET requests over HTTPS.

Authorization

The Beauhurst API requires authentication in the form of an API key. To obtain an API key, please contact your subscription's account manager at Beauhurst. Be sure to keep this key private and secure.

", "version": "beauhurstapi" }, "security": [ { "ApiKey": [] } ], "paths": { "/v1/people": { "get": { "operationId": "v1_people_list", "summary": "Returns paginated data on people", "description": "Can filter the results by parameters.\nReturns paginated data on these companies.\nUse the 'includes' parameter to select which fields you want", "parameters": [ { "name": "sort", "in": "query", "description": "Which field to use when ordering the results.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page.", "required": false, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "description": "The initial index from which to return the results.", "required": false, "schema": { "type": "integer" } }, { "name": "includes", "in": "query", "required": true, "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "id", "beauhurst_url", "basic_details", "contact_information", "current_shareholdings", "directorships", "secretary_positions", "company_positions", "fund_positions" ] } } }, { "name": "collection_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 6, "maxLength": 6 } }, { "name": "person_ids", "in": "query", "description": "Beauhurst ID for person", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string", "maxLength": 6, "minLength": 6 } } }, { "name": "modified_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "email", "in": "query", "description": "List of email addresses to filter by", "required": false, "explode": true, "schema": { "type": "array", "items": { "type": "string", "format": "email", "minLength": 1 } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "required": [ "total", "limit", "offset", "count", "results" ], "type": "object", "properties": { "total": { "description": "Total number of items available.", "type": "integer" }, "limit": { "description": "Number of results to return per page.", "type": "integer" }, "offset": { "description": "The initial index from which to return the results.", "type": "integer" }, "count": { "description": "number of results returned", "type": "integer" }, "results": { "type": "array", "items": { "required": [ "id", "basic_details", "contact_information", "current_shareholdings", "directorships", "secretary_positions", "company_positions", "fund_positions" ], "type": "object", "properties": { "id": { "title": "Id", "type": "string", "minLength": 1 }, "beauhurst_url": { "title": "Beauhurst url", "type": "string", "readOnly": true }, "basic_details": { "required": [ "name", "gender", "nationality", "country_of_residence" ], "type": "object", "properties": { "name": { "title": "Name", "type": "string", "minLength": 1 }, "date_of_birth": { "title": "Date of birth", "type": "string", "readOnly": true }, "age": { "title": "Age", "type": "string", "readOnly": true }, "gender": { "title": "Gender", "type": "string", "minLength": 1 }, "nationality": { "type": "array", "items": { "type": "string", "nullable": true } }, "country_of_residence": { "type": "array", "items": { "type": "string", "nullable": true } } } }, "contact_information": { "required": [ "email_addresses" ], "type": "object", "properties": { "email_addresses": { "type": "array", "items": { "type": "string", "nullable": true } }, "linkedin_url": { "title": "Linkedin url", "type": "string", "readOnly": true } } }, "current_shareholdings": { "type": "array", "items": { "required": [ "company_id", "company_name", "share_class", "percentage_owned", "estimated_value" ], "type": "object", "properties": { "company_id": { "title": "Company id", "type": "string", "minLength": 1 }, "company_name": { "title": "Company name", "type": "string", "minLength": 1 }, "share_class": { "title": "Share class", "type": "string", "maxLength": 256, "minLength": 1 }, "percentage_owned": { "title": "Percentage owned", "type": "number", "format": "decimal" }, "estimated_value": { "title": "Estimated value", "type": "integer" } } } }, "directorships": { "type": "array", "items": { "required": [ "company_id", "company_name", "email", "from_date", "until_date" ], "type": "object", "properties": { "company_id": { "title": "Company id", "type": "string", "minLength": 1 }, "company_name": { "title": "Company name", "type": "string", "minLength": 1 }, "email": { "title": "Email", "type": "string", "minLength": 1 }, "from_date": { "title": "From date", "type": "string", "format": "date" }, "until_date": { "title": "Until date", "type": "string", "format": "date" } } } }, "secretary_positions": { "type": "array", "items": { "required": [ "company_id", "company_name", "email", "from_date", "until_date" ], "type": "object", "properties": { "company_id": { "title": "Company id", "type": "string", "minLength": 1 }, "company_name": { "title": "Company name", "type": "string", "minLength": 1 }, "email": { "title": "Email", "type": "string", "minLength": 1 }, "from_date": { "title": "From date", "type": "string", "format": "date" }, "until_date": { "title": "Until date", "type": "string", "format": "date" } } } }, "company_positions": { "type": "array", "items": { "required": [ "company_id", "company_name", "job_functions", "email", "until_date" ], "type": "object", "properties": { "company_id": { "title": "Company id", "type": "string", "minLength": 1 }, "company_name": { "title": "Company name", "type": "string", "minLength": 1 }, "title": { "title": "Title", "type": "string", "maxLength": 256 }, "job_functions": { "type": "array", "items": { "type": "string", "nullable": true } }, "is_founder": { "title": "Is founder", "description": "Was this person a founder?", "type": "boolean" }, "email": { "title": "Email", "type": "string", "minLength": 1 }, "until_date": { "title": "Until date", "type": "string", "format": "date" } } } }, "fund_positions": { "type": "array", "items": { "required": [ "fund_id", "fund_name", "email" ], "type": "object", "properties": { "fund_id": { "title": "Fund id", "type": "string", "minLength": 1 }, "fund_name": { "title": "Fund name", "type": "string", "minLength": 1 }, "title": { "title": "Title", "type": "string", "maxLength": 256 }, "email": { "title": "Email", "type": "string", "minLength": 1 }, "currently_active": { "title": "Currently active", "description": "Is this person currently at the organization?", "type": "boolean" } } } } } } } } } } } } }, "tags": [ "v1" ] }, "parameters": [] } }, "servers": [ { "url": "https://platform.beauhurst.com/_api" } ], "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "name": "Authorization", "description": "Beauhurst API key", "in": "header" } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```