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

# Find or create a contact

`POST /v1/contacts/find-or-create`

## Request

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

Looks up exactly one identifier through `lookup: { type, value }`. Returns `{ contact, created: false }` unchanged when it exists. Otherwise creates the lookup identity (or external ID), applies `create` attributes, and returns `{ contact, created: true }`. Additional addresses belong in `create.identities`, custom fields in `create.profile.customFields`; custom field keys must be defined and values must match their types. An external ID lookup cannot be contradicted by `create.externalId`. Creation returns HTTP 409 ConflictError if an externalId or address belongs to another contact; the conflicting field is named and no contact is created. Use the update endpoint to change an existing contact.

## Request body

- object
  - `namespaceId` string
  - `lookup` union, required
    - object
      - `type` 'email', required
      - `value` string, required
    - object
      - `type` 'phone', required
      - `value` string, required
    - object
      - `type` 'externalId', required
      - `value` string, required
  - `create` object, nullable
    - `name` string, nullable
    - `displayName` string, nullable
    - `avatar` string, nullable
    - `identities` ContactIdentityInput[], nullable
      - `type` 'email' | 'phone', required
      - `identifier` string, required
      - `verified` boolean, nullable
    - `profile` ContactProfile
      - `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
    - `externalId` string, nullable

## Response `200`

Success

- object
  - `contact` Contact, required
    - `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
  - `created` boolean, required

## Other responses

- `401`: UnauthorizedError
- `402`: PaymentRequiredError
- `403`: ForbiddenError
- `404`: ResourceNotFoundError
- `409`: ConflictError
- `422`: ValidationError
- `500`: InternalError
- `502`: BillingProviderError
- `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)