---
title: "Bulk lookup people by identity"
method: POST
path: "/api/v1/people/lookup"
tags: ["People"]
---

# Bulk lookup people by identity

`POST /api/v1/people/lookup`

## Request

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

Use this endpoint to check whether a batch of contacts already exist in your Atlas account - before importing or syncing them from another system.

You send a list of contact details (up to 100 at a time), and Atlas will automatically figure out what type each one is based on its format - for example, anything that looks like an email address will be treated as an email, a URL containing "linkedin.com" will be treated as a LinkedIn profile, and a string of digits will be treated as a phone number.

For each item you send, Atlas tells you:
- Whether it recognised the format (if not, it returns `"invalid identity format"`)
- Whether a person with that contact detail already exists in your agency
- The ID of that person, if they exist (useful for linking records)

This is particularly useful when you have a spreadsheet or external system full of contacts and you want to quickly find out which ones are already in Atlas before deciding what to do with the rest.

## Request body

- LookupPeoplePayload
  - `identities` string[], required: List of identity strings to look up (max 100). Type is auto-detected from the value pattern.

## Response `200`

Lookup results, one entry per input identity in the same order

- object
  - `status` 'ok', required
  - `data` object[], required
    - `type` string, required: Auto-detected identity type, or "invalid identity format"
    - `value` string, required: Original input value
    - `exists` boolean, required
    - `personId` string, uuid, nullable, required

## 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-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/lookup/post.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)