> ## Documentation Index > Fetch the complete documentation index at: https://talktohumans.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # Search people > Finds new people on LinkedIn ## OpenAPI ````yaml /developers/openapi.yaml post /v1/people/search openapi: 3.0.3 info: title: TalkToHumans Public API version: 1.0.0 license: name: Proprietary description: > Read and organize the LinkedIn organization data your team already manages in TalkToHumans: accounts, contacts, signals, content, tags, notes, custom fields, sequence state, conversations, templates, and views. servers: - url: https://api.talktohumans.app description: TalkToHumans API security: - bearerAuth: [] tags: - name: Organization description: Organization details for the current API key. - name: LinkedIn description: LinkedIn accounts, contacts, companies, and conversations. - name: Activity description: Activity for organization reporting. - name: Enrich description: Profile enrichment for LinkedIn contacts and companies. - name: Views description: Saved TalkToHumans views. - name: Sequences description: Sequences of contacts and conversations. - name: Templates description: Message and sequence templates. - name: Custom fields description: Custom fields for contacts and companies. - name: Tags description: Tags for contacts and companies. - name: Content description: LinkedIn posts and comments, and the people who engage with them. - name: Agents description: Playbooks and feedback for AI agents, shared with the MCP. paths: /v1/people/search: post: tags: - LinkedIn summary: Search people description: Finds new people on LinkedIn operationId: searchPeople requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchPeopleRequest' example: job_titles: - Head of Sales - VP Sales locations: - Paris industries: - Software Development company_sizes: - 11-50 - 51-200 responses: '200': description: > One page of 25 people. They aren't contacts yet: import them with `POST /v1/contacts` and their `linkedin_url`. Each page costs 10 credits, nothing when the organization read it within 24 hours. content: application/json: schema: $ref: '#/components/schemas/SearchPeopleEnvelope' example: data: people: - name: Alex Nguyen first_name: Alex last_name: Nguyen primary_role_title: Head of Sales primary_company_name: Example Co primary_company_linkedin_url: https://www.linkedin.com/company/1000050 primary_company_industry: Software Development location: Paris, Île-de-France, France linkedin_url: >- https://www.linkedin.com/in/ACwAAA0000000000000000000000000000000000 total_results: 2537 pagination: limit: 25 has_more: true next_cursor: eyJxdWVyeV9rZXkiOiIuLi4iLCJwYWdlIjoyfQ charged_credits: 10 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientCredits' '403': $ref: '#/components/responses/AccountScopedForbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalServerError' components: schemas: SearchPeopleRequest: type: object additionalProperties: false description: > At least one filter besides `exclude`, or `sales_navigator_url` alone. List filters match any of their values, and people must match every filter set. properties: account_id: type: string description: >- LinkedIn account ID returned by `GET /v1/accounts`. Required when the organization has multiple LinkedIn accounts. pattern: ^[1-9][0-9]*$ keywords: type: string maxLength: 200 description: >- Words to search for, such as a skill or a name. Supports LinkedIn's `AND`, `OR` and `NOT`. job_titles: type: array maxItems: 20 description: Current job titles, such as `Head of Sales`. items: type: string past_job_titles: type: array maxItems: 20 description: Past job titles. items: type: string company_linkedin_urls: type: array maxItems: 20 description: >- LinkedIn company page URLs of their current employer, such as `https://www.linkedin.com/company/google`. items: type: string past_company_linkedin_urls: type: array maxItems: 20 description: LinkedIn company page URLs of their past employers. items: type: string school_linkedin_urls: type: array maxItems: 20 description: >- LinkedIn school page URLs, such as `https://www.linkedin.com/school/stanford-university`. items: type: string locations: type: array maxItems: 20 description: Locations, such as `Paris` or `United States`. items: type: string industries: type: array maxItems: 20 description: >- Industries of their current employer, as LinkedIn company pages name them, such as `Software Development` or `Financial Services`. An unknown one fails with the closest names. items: type: string seniorities: type: array maxItems: 20 description: >- Seniority levels (`In Training`, `Entry Level`, `Senior`, `Strategic`, `Entry Level Manager`, `Experienced Manager`, `Director`, `Vice President`, `CXO` or `Owner / Partner`). items: type: string company_sizes: type: array maxItems: 20 description: >- Employee counts of their current employer (`self-employed`, `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000` or `10001+`). items: type: string languages: type: array maxItems: 20 description: >- Languages of their LinkedIn profile (`Arabic`, `Bahasa Indonesia`, `Chinese`, `Czech`, `Danish`, `Dutch`, `English`, `French`, `German`, `Italian`, `Japanese`, `Korean`, `Malay`, `Norwegian`, `Polish`, `Portuguese`, `Romanian`, `Russian`, `Spanish`, `Swedish`, `Tagalog` or `Turkish`). items: type: string exclude: $ref: '#/components/schemas/SearchPeopleExclusions' sales_navigator_url: type: string description: > Sales Navigator lead search URL, copied from the address bar, instead of every other filter. Filters tied to your own Sales Navigator account (lead and account lists, connections, past colleagues, saved leads, lead interactions, personas, profile viewers, company followers, shared experiences) aren't supported. cursor: type: string description: >- Cursor returned as `data.pagination.next_cursor` by the previous call, with the same filters. Each page costs credits. SearchPeopleEnvelope: type: object additionalProperties: false required: - data properties: data: $ref: '#/components/schemas/SearchPeopleResponse' SearchPeopleExclusions: type: object additionalProperties: false description: >- People to leave out, matching any of these values. Values are as in the filters of the same name. properties: job_titles: type: array maxItems: 20 description: Current job titles. items: type: string past_job_titles: type: array maxItems: 20 description: Past job titles. items: type: string company_linkedin_urls: type: array maxItems: 20 description: LinkedIn company page URLs of current employers. items: type: string past_company_linkedin_urls: type: array maxItems: 20 description: LinkedIn company page URLs of past employers. items: type: string school_linkedin_urls: type: array maxItems: 20 description: LinkedIn school page URLs. items: type: string locations: type: array maxItems: 20 description: Locations. items: type: string industries: type: array maxItems: 20 description: Industries of the current employer. items: type: string seniorities: type: array maxItems: 20 description: Seniority levels. items: type: string SearchPeopleResponse: type: object additionalProperties: false required: - people - total_results - pagination - charged_credits properties: people: type: array items: $ref: '#/components/schemas/SearchPerson' total_results: type: integer description: >- People LinkedIn counts for this search. At most 100 pages can be read. pagination: $ref: '#/components/schemas/Pagination' charged_credits: type: integer format: int64 Error: type: object additionalProperties: false required: - code - message properties: code: type: string description: Machine-readable error code. enum: - unauthorized - forbidden - not_found - bad_request - internal_error - conflict - rate_limit_exceeded - account_shared_access_required - linkedin_not_connected - workspace_setup_required - billing_payment_failed - billing_subscription_incomplete - billing_subscription_expired - billing_grace_period - billing_feature_not_available - billing_insufficient_credits - billing_invalid - enrichment_failed - enrichment_in_progress - linkedin_profile_not_found message: type: string description: Human-readable error message. debug: type: string description: Development-only debug details. SearchPerson: type: object additionalProperties: false description: > A person found on LinkedIn, not a contact yet, so there is no `contact_id`: `linkedin_url` carries a Sales Navigator ID that only `POST /v1/contacts` resolves. Importing skips people who already are contacts. required: - name - linkedin_url properties: name: type: string first_name: type: string last_name: type: string primary_role_title: type: string primary_company_name: type: string primary_company_linkedin_url: type: string format: uri primary_company_industry: type: string location: type: string linkedin_url: type: string format: uri description: Import this person with `POST /v1/contacts`. avatar_url: type: string format: uri Pagination: type: object additionalProperties: false required: - limit - has_more properties: limit: type: integer format: int32 example: 10 has_more: type: boolean next_cursor: type: string description: Cursor for the next page. Omitted when there are no more results. responses: BadRequest: description: Invalid request. `message` explains what to fix. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: bad_request message: >- field "account_id" must be a string, got number; IDs are strings, e.g. "42" Unauthorized: description: >- Missing, malformed, invalid, or retired API key, or an invalid or expired login access token. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missingAuthorization: value: code: unauthorized message: Authorization header is required invalidAuthorizationFormat: value: code: unauthorized message: Authorization header must use Bearer scheme invalidAPIKey: value: code: unauthorized message: Invalid API key invalidAccessToken: value: code: unauthorized message: Invalid or expired access token InsufficientCredits: description: Not enough credits available. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: billing_insufficient_credits message: Not enough credits available AccountScopedForbidden: description: >- API access is not enabled for the organization, the API key cannot resolve to an active organization user, the login has no workspace yet, or the credential cannot access the requested LinkedIn account. content: application/json: schema: $ref: '#/components/schemas/Error' examples: accountSharedAccessRequired: summary: Requested account is not accessible to this credential value: code: account_shared_access_required message: >- This account is not shared-access enabled for API or MCP. Ask an admin to enable shared access before using this account from this credential. forbidden: value: code: forbidden message: you don't have access to this organization featureUnavailable: value: code: billing_feature_not_available message: >- Feature 'TalkToHumansAPI' is not available in your current plan insufficientCredits: value: code: billing_insufficient_credits message: Insufficient credits apiKeyPrincipalInvalid: value: code: forbidden message: >- This API key is no longer linked to an active organization user. Ask an organization admin to regenerate it workspaceSetupRequired: value: code: workspace_setup_required message: >- This TalkToHumans sign-in has no workspace yet. Open https://app.talktohumans.app, sign in with the same email to finish setting up TalkToHumans, then try again. RateLimited: description: >- Rate limit exceeded. Public routes allow 50 requests per 10 seconds per IP and endpoint. headers: Retry-After: description: Seconds to wait before retrying the request. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limit_exceeded message: Rate limit exceeded InternalServerError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: internal_error message: An internal error occurred securitySchemes: bearerAuth: type: http scheme: bearer description: > Pass `Authorization: Bearer `, where the credential is either: - an API key (`sk_…`), generated by an organization admin in Settings, for scripts and automation; - an access token from `tth auth login` (the TalkToHumans CLI), which any member of the workspace can use. Both resolve to the same organization and user. A login token acts in the user's workspace: one with no workspace yet returns `403 workspace_setup_required`, and one in several workspaces returns `403 forbidden` (use an API key instead). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.