---
title: "Find the single closest person (per-field)"
method: GET
path: "/api/v1/ackdb/persons/search"
tags: ["ackDB"]
---

# Find the single closest person (per-field)

`GET /api/v1/ackdb/persons/search`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/ackdb/persons/search`
- Auth: HTTP bearer

The person analog of `/contacts/search` and `/entities/search`. Send whichever field you have — params are ANDed and at least one is required: `q` (name + every key value), `name`, `email`, `linkedin`, `identity` (any key value, optionally pinned with `identityType`). `email`/`linkedin` are normalized before matching, so a raw pasted URL or mixed-case address still lands an exact-tier hit.

Ranked case-insensitive substring (exact > prefix > contains); returns ONE active person, hydrated exactly like `GET /persons/{personId}` (person + keys + affiliations + recent events), plus a `matchedOn` block. `matchedOn.contacts` names WHERE the matched value lives: every stint whose edge carries it verbatim (email / contact identity links; former stints included, disabled excluded), each with `entity: { entityId, name, domain }` — so a hit through an old employer's address is attributable even though `data` reports the current one. A `name` hit returns `[]` (a name sits on every stint alike). No match → 404.

## Query parameters

- `q` string
- `name` string
- `email` string
- `linkedin` string
- `identity` string
- `identityType` string
- `contactLimit` integer
- `eventLimit` integer

## Response `200`

`{ data: PersonProfile, matchedOn: { field, value, tier, contacts: [{ contactId, status, title, startedAt, endedAt, entity: { entityId, name, domain } }] } }`.

- object
  - `data` unknown, required

## Other responses

- `404`: No person matches the given fields.
- `422`: No field param provided (need ≥1 of q/name/email/linkedin/identity).

---

[API](https://skmtc.dev/floqer/apis/floqer-public-api.md) - [All operations](https://skmtc.dev/floqer/apis/floqer-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/floqer/apis/floqer-public-api/revisions/fce50dc07b20?raw)