---
title: "Find a contact"
method: POST
path: "/v1/contacts/find"
tags: ["Contacts"]
---

# Find a contact

`POST /v1/contacts/find`

## Request

- Base URL: `https://api.samva.dev`
- URL: `https://api.samva.dev/v1/contacts/find`
- Auth: API key in header `x-api-key`

Looks up a single contact by exactly one of email address, phone number, or external ID and returns null when no contact matches. A phone number without `+` is read in the organization's default region.

## Request body

- object
  - `namespaceId` string
  - `email` string, nullable
  - `phone` string, nullable
  - `externalId` string, nullable

## Response `200`

Success

- Contact
  - `id` string, required
  - `namespaceId` string, required
  - `name` string, required
  - `displayName` string, nullable, required
  - `avatar` string, nullable, required
  - `status` 'active' | 'paused' | 'blocked' | 'archived', required
  - `statusReason` string, nullable, required
  - `externalId` string, nullable, required
  - `identities` ContactIdentity[], required
    - `id` string, required
    - `type` 'email' | 'phone', required
    - `identifier` string, required
    - `verified` boolean, required
    - `channels` ContactIdentityChannel[], required
      - `channel` 'email', required
      - `reachability` 'unknown' | 'reachable' | 'unreachable', required
      - `consent` ContactConsent, required
        - `status` 'opted_in' | 'opted_out', required
        - `source` string, required
        - `capturedAt` string, required
        - `proof` JsonObject, required
  - `profile` ContactProfile, required
    - `firstName` string, nullable
    - `lastName` string, nullable
    - `company` string, nullable
    - `jobTitle` string, nullable
    - `location` ContactLocation
      - `country` string, required
      - `state` string, required
      - `city` string, required
      - `timezone` string, required
    - `customFields` ContactCustomFields
    - `source` 'api' | 'import' | 'manual' | 'form', nullable
  - `preferences` ContactPreferences, required
    - `preferredChannels` string[], nullable
    - `language` string, nullable
    - `timezone` string, nullable
    - `notifications` object, nullable
      - `email` boolean, nullable
      - `quiet_hours` object, nullable
        - `start` string, required
        - `end` string, required
  - `tags` string[], required
  - `metadata` JsonObject, required
  - `createdAt` string, required
  - `updatedAt` string, required

## Other responses

- `401`: UnauthorizedError
- `403`: ForbiddenError
- `404`: ResourceNotFoundError
- `409`: ConflictError
- `422`: ValidationError
- `500`: InternalError
- `504`: GatewayTimeoutError

---

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