# Search People

Find people on LinkedIn by title, company, location, seniority and more.

Searches LinkedIn live and returns one page of people, up to about 25 per page. Combine as many filters as you like: every filter narrows the result, and values inside one list are alternatives (`["CFO", "CEO"]` means CFO *or* CEO).

At least one filter is required. Page through the result with `next_cursor`, which keeps the result stable from page to page. The source stops at page 100.

Every list filter takes 1 to 20 values of at most 200 characters. A value cannot contain a comma.

## Request

```http
POST https://geteem.com/api/v1/person/search
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

### Body parameters

- **`keywords`** `string` — Free text, matched like the LinkedIn search box: name, headline, company.
- **`current_job_titles`** `string[]` — Job titles the person holds now, e.g. `["CFO", "Head of Finance"]`. Title matching is fuzzy: results are ranked by how well the title matches, so people with a different title can still appear. Add `seniority_levels` or `functions` for a strict filter.
- **`past_job_titles`** `string[]` — Job titles the person held before.
- **`current_companies`** `string[]` — Where the person works now: company names or LinkedIn company URLs (`https://www.linkedin.com/company/acme`). URLs are the most precise.
- **`past_companies`** `string[]` — Where the person worked before; same format as `current_companies`.
- **`exclude_current_companies`** `string[]` — Leave out people who work at these companies now.
- **`locations`** `string[]` — Where the person is based: country, region or city names in English, e.g. `["Belgium", "Amsterdam"]`.
- **`exclude_locations`** `string[]` — Leave out people based here.
- **`schools`** `string[]` — Schools or universities the person attended.
- **`first_names`** `string[]` — Exact first names.
- **`last_names`** `string[]` — Exact last names.
- **`seniority_levels`** `string[]` — Seniority of the current position. One of: `in_training`, `entry_level`, `senior`, `strategic`, `entry_level_manager`, `experienced_manager`, `director`, `vice_president`, `cxo`, `owner_partner`.
- **`exclude_seniority_levels`** `string[]` — Leave out these seniority levels. One of: `in_training`, `entry_level`, `senior`, `strategic`, `entry_level_manager`, `experienced_manager`, `director`, `vice_president`, `cxo`, `owner_partner`.
- **`functions`** `string[]` — Department of the current position. One of: `accounting`, `administrative`, `arts_and_design`, `business_development`, `community_and_social_services`, `consulting`, `education`, `engineering`, `entrepreneurship`, `finance`, `healthcare_services`, `human_resources`, `information_technology`, `legal`, `marketing`, `media_and_communication`, `military_and_protective_services`, `operations`, `product_management`, `program_and_project_management`, `purchasing`, `quality_assurance`, `real_estate`, `research`, `sales`, `customer_success_and_support`.
- **`exclude_functions`** `string[]` — Leave out these departments. One of: `accounting`, `administrative`, `arts_and_design`, `business_development`, `community_and_social_services`, `consulting`, `education`, `engineering`, `entrepreneurship`, `finance`, `healthcare_services`, `human_resources`, `information_technology`, `legal`, `marketing`, `media_and_communication`, `military_and_protective_services`, `operations`, `product_management`, `program_and_project_management`, `purchasing`, `quality_assurance`, `real_estate`, `research`, `sales`, `customer_success_and_support`.
- **`company_headcounts`** `string[]` — Size of the current employer, as a headcount range. One of: `self-employed`, `1-10`, `11-50`, `51-200`, `201-500`, `501-1000`, `1001-5000`, `5001-10000`, `10001+`.
- **`years_of_experience`** `string[]` — Total years of work experience. One of: `less_than_1`, `1_to_2`, `3_to_5`, `6_to_10`, `more_than_10`.
- **`years_at_current_company`** `string[]` — Years at the current employer. One of: `less_than_1`, `1_to_2`, `3_to_5`, `6_to_10`, `more_than_10`.
- **`profile_languages`** `string[]` — Language of the LinkedIn profile. One of: `ar`, `cs`, `da`, `de`, `en`, `es`, `fr`, `in`, `it`, `ja`, `ko`, `ms`, `nl`, `no`, `pl`, `pt`, `ro`, `ru`, `sv`, `tl`, `tr`, `zh`.
- **`recently_changed_jobs`** `boolean` — Only people who started a new position in the last 90 days.
- **`posted_on_linkedin`** `boolean` — Only people who posted on LinkedIn in the last 30 days.
- **`page`** `integer` — Page to fetch, 1 to 100. Defaults to 1.
- **`cursor`** `string` — The `next_cursor` of the previous response. Takes precedence over `page`.

## Response

- **`results`** `object[]` — The people on this page. See the fields below.
- **`results[].linkedin_url`** `string` — Profile URL. Search returns the member-id form (`/in/ACwAA…`); it works as input for Enrich People, which returns the public URL.
- **`results[].linkedin_id`** `string | null` — LinkedIn member id.
- **`results[].first_name`** `string | null` — First name.
- **`results[].last_name`** `string | null` — Last name.
- **`results[].full_name`** `string | null` — First and last name together.
- **`results[].picture_url`** `string | null` — Profile photo. LinkedIn photo URLs expire after a few weeks.
- **`results[].location`** `object` — `text`: where the person is based, as LinkedIn shows it.
- **`results[].current_positions`** `object[]` — Positions held now: `title`, `company_name`, `company_linkedin_url`, `started_on` (`year`, `month`), `tenure_at_position` and `tenure_at_company` (`years`, `months`).
- **`pagination`** `object` — `page`, `total_pages`, `total_results` (as reported by the source) and `next_cursor` (null on the last page).
- **`credits_used`** `integer` — Credits this call used: one per returned row.

## Credits

5 credits per returned row. Errors and empty lookups are free. The cost of every call is in `credits_used` and in the `X-Credits-Used` header.

## Errors

- **400** `invalid_request` — The body is not valid JSON, a field is unknown or has the wrong type, or a value is not allowed.
- **401** `authentication_error` — The Authorization header is missing, or the key is unknown or revoked.
- **403** `permission_error` — API access is not part of your plan, or your account is suspended.
- **429** `rate_limit_error` — More than 60 requests per minute, or more than 3 at the same time, on one key. Wait for the Retry-After header.
- **429** `daily_limit_reached` — The request could take your organization over its daily credit limit. The limit resets at midnight (Europe/Brussels).
- **502** `upstream_error` — The data source did not answer. Retry later.
- **503** `service_unavailable` — The API is temporarily unavailable. Retry later.
- **500** `internal_error` — Something went wrong on our side.

## Example

### Example request

```bash
curl -X POST "https://geteem.com/api/v1/person/search" \
  -H "Authorization: Bearer $SIMBA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "current_job_titles": [
      "CFO",
      "Head of Finance"
    ],
    "locations": [
      "Belgium"
    ],
    "company_headcounts": [
      "51-200",
      "201-500"
    ],
    "recently_changed_jobs": true
  }'
```

### Example response

```json
{
  "results": [
    {
      "linkedin_url": "https://www.linkedin.com/in/ACwAAExample123",
      "linkedin_id": "ACwAAExample123",
      "first_name": "Jane",
      "last_name": "Example",
      "full_name": "Jane Example",
      "picture_url": null,
      "location": {
        "text": "Ghent, Flemish Region, Belgium"
      },
      "current_positions": [
        {
          "title": "Chief Financial Officer",
          "company_name": "Acme Analytics",
          "company_linkedin_url": "https://www.linkedin.com/company/acme-analytics",
          "started_on": {
            "year": 2026,
            "month": 7
          },
          "tenure_at_position": {
            "years": 0,
            "months": 2
          },
          "tenure_at_company": {
            "years": 0,
            "months": 2
          }
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "total_pages": 6,
    "total_results": 131,
    "next_cursor": "eyJwIjoyfQ"
  },
  "credits_used": 25
}
```