> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nuvia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Check contact identifiers

> Read-only. Tells you what `POST /v1/contacts` would do with these identifiers, so the form can warn before saving.

- **Lookup order:** email, LinkedIn and phone.
- **`new`:** no contact in the company has the identifiers.
- **`existing`:** the contact in `contact` would be reused; `matches_count` says how many contacts matched by the `matched_by` key.
- **`conflict`:** different identifiers point to different contacts; `conflicts` returns each one.
- **`exclude_contact_id`:** ignores this contact (the edit form sends the contact itself).



## OpenAPI

````yaml /en/openapi.json post /v1/contacts/identity-check
openapi: 3.0.0
info:
  title: Nuvia API - Company
  description: API documentation for companies
  version: '1.0'
  contact: {}
servers:
  - url: https://api.nuvia.ai
security: []
tags:
  - name: messages
    x-group: Mensagens
  - name: contacts
    x-group: Contatos
  - name: campaigns
    x-group: Campanhas
  - name: tables
    x-group: Tabelas e Listas
  - name: agents
    x-group: Agentes
  - name: conversations
    x-group: Conversas
  - name: inboxes
    x-group: Caixas de Entrada
  - name: knowledge
    x-group: Base de Conhecimento
  - name: Webhooks
    x-group: Webhooks
  - name: campaign-enrollments
    x-group: Inscrições em Campanha
  - name: custom-fields
    x-group: Campos Customizados
  - name: resources
    x-group: Arquivos e Anexos
  - name: hubspot
    x-group: HubSpot
paths:
  /v1/contacts/identity-check:
    post:
      tags:
        - contacts
      summary: Check contact identifiers
      description: >-
        Read-only. Tells you what `POST /v1/contacts` would do with these
        identifiers, so the form can warn before saving.


        - **Lookup order:** email, LinkedIn and phone.

        - **`new`:** no contact in the company has the identifiers.

        - **`existing`:** the contact in `contact` would be reused;
        `matches_count` says how many contacts matched by the `matched_by` key.

        - **`conflict`:** different identifiers point to different contacts;
        `conflicts` returns each one.

        - **`exclude_contact_id`:** ignores this contact (the edit form sends
        the contact itself).
      operationId: ContactController_checkContactIdentity
      parameters:
        - name: x-company-id
          in: header
          description: >-
            Target company identifier. Required only for global API keys
            (type=global). Ignored for company API keys and human users.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactIdentityCheckDto'
      responses:
        '200':
          description: Check result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactIdentityCheckResponseDto'
      security:
        - JWT-auth: []
components:
  schemas:
    ContactIdentityCheckDto:
      type: object
      properties:
        email:
          type: string
          description: Email to check. Only counts as an identifier if it contains "@".
        linkedin_identifier:
          type: string
          description: LinkedIn profile URL or just the profile name.
        phone_number:
          type: string
          description: >-
            Phone (area code + number, without the country code). A phone that
            doesn't form a valid number is ignored in the check.
        country_code:
          type: string
          description: 'Phone country calling code. Example: 55.'
        exclude_contact_id:
          type: string
          description: >-
            Contact to ignore in the check. The edit form sends the contact
            itself: a value equal to its own isn't a conflict.
          pattern: ^[0-9a-fA-F]{24}$
    ContactIdentityCheckResponseDto:
      type: object
      properties:
        status:
          type: string
          enum:
            - new
            - existing
            - conflict
          description: >-
            `new`: no contact has the identifiers. `existing`: the POST would
            reuse `contact`. `conflict`: different identifiers point to
            different contacts.
        matched_by:
          description: Identifier that matched
          type: string
          enum:
            - email
            - linkedin
            - phone
          nullable: true
        matches_count:
          type: number
          description: How many contacts in the company matched by the `matched_by` key.
        contact:
          description: Contact that would be reused. null for `new` and `conflict`.
          type: object
          properties:
            _id:
              description: Contact ID
              type: string
            name:
              type: string
              description: Contact name
            email:
              description: Contact's email
              type: string
            phone_number:
              description: The contact's phone
              type: string
            country_code:
              description: Phone country calling code
              type: string
            linkedin_identifier:
              description: The contact's LinkedIn identifier
              type: string
          required:
            - _id
          nullable: true
        conflicts:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                enum:
                  - email
                  - linkedin
                  - phone
                description: Identifier that matched
              contact:
                type: object
                properties:
                  _id:
                    description: Contact ID
                    type: string
                  name:
                    type: string
                    description: Contact name
                  email:
                    description: Contact's email
                    type: string
                  phone_number:
                    description: The contact's phone
                    type: string
                  country_code:
                    description: Phone country calling code
                    type: string
                  linkedin_identifier:
                    description: The contact's LinkedIn identifier
                    type: string
                required:
                  - _id
            required:
              - field
              - contact
          description: >-
            For `conflict`, the contact for each identifier. Empty in the other
            cases.
      required:
        - status
        - matched_by
        - matches_count
        - contact
        - conflicts
  securitySchemes:
    JWT-auth:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: JWT authentication token

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.