---
title: "Search people by identity"
method: GET
path: "/api/v1/people/search"
tags: ["People"]
---

# Search people by identity

`GET /api/v1/people/search`

## Request

- Base URL: `https://api.recruitwithatlas.com`
- URL: `https://api.recruitwithatlas.com/api/v1/people/search`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/recruitwithatlas/apis/atlas-api/docs/api/v1/people/search/get.ts> (a function with typed inputs; its response is checked against the schema)

Use this endpoint to look up a specific person in your Atlas account using a contact detail you already know - such as their email address, phone number, or LinkedIn profile URL.

For example, if someone fills out a form on your website and you have their email address, you can use this endpoint to instantly check whether they already exist in Atlas and retrieve their full record.

You must provide at least one of: email, phone, or LinkedIn URL. Atlas will search your agency's data and return any matching people along with their name, current role, current company, and the contact details (identities) that matched your search - each with its `active` state and `inactiveReason`, so you can tell an unsubscribed email from a bounced one. To get every identity a person has, use `GET /api/v1/people/{personId}/identities`.

Phone numbers are expanded server-side into every form they may be stored in (national, international, with and without a leading 0 or +), so `07935929797` and `+447935929797` find the same person. A number Atlas cannot parse expands to nothing and is not a searchable value.

If none of the values you supply resolves to something searchable - for example `phones` on its own containing only an unparseable number - the request is rejected with 422 rather than searched, because a search with no usable filter would otherwise match everything.

If the filters are valid but nothing matches, an empty list is returned - that is not an error.

## Query parameters

- `emails` string: Comma-separated email addresses
- `phones` string: Comma-separated phone numbers. Each value is expanded server-side into every form it may be stored in (national, international, with and without a leading 0 or +). A number that cannot be parsed expands to nothing and is therefore not a searchable value.
- `linkedinUrls` string: Comma-separated LinkedIn URLs

## Response `200`

Matching people with their identities

- object
  - `status` 'ok', required
  - `data` object[], required
    - `id` string, uuid, required
    - `firstName` string, nullable, required: First name
    - `lastName` string, nullable, required: Last name
    - `headlineRole` string, nullable, required: Current role/job title
    - `headlineCompanyName` string, nullable, required: Current company name
    - `identities` object[], required
      - `identityId` string, uuid, required: Identity ID - stable across reads, so use it as the key when syncing identities
      - `type` string, required
      - `value` string, required
      - `active` boolean, required: `false` when the identity is inactive; `inactiveReason` says why
      - `inactiveReason` 'bounced' | 'other' | 'unsubscribed' | 'suppressed' | 'null', nullable, required: Why the identity is inactive: `unsubscribed` - the person opted out of email; `bounced` - email to the address bounced; `suppressed` - the address is on the agency's suppression list; `other` - deactivated for another reason. `null` when the identity is active, or when it was deactivated without a recorded reason.

## Other responses

- `401`: Unauthorized - missing or invalid API key
- `422`: Validation error - the request failed schema validation (`errors.fieldErrors`) or a business rule (`errors.formErrors`)
- `429`: Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the "Rate limits" section of the introduction for details.
- `500`: Internal server error

## Changes

- **2026-11-03** `158ee454751c`: 1 warning
  - added the new `undefined` enum value to the `data/items/identities/items/inactiveReason` response property for the response status `200`
- **2026-10-20** `b7e1215476a1`: 2 info
  - added the required property `data/items/identities/items/identityId` to the response with the `200` status
  - added the required property `data/items/identities/items/inactiveReason` to the response with the `200` status
- **2026-10-03** `cd4bc8bbd95e`: 1 info
  - added the optional property `error` to the response with the `422` status

[Operation history](https://skmtc.dev/recruitwithatlas/apis/atlas-api/changes/api/v1/people/search/get.md)

---

[API](https://skmtc.dev/recruitwithatlas/apis/atlas-api.md) - [All operations](https://skmtc.dev/recruitwithatlas/apis/atlas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/recruitwithatlas/apis/atlas-api/revisions/158ee454751c?raw)