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

# Get Contact

> Fetch a single contact by `email` or `cnvContactId`. Provide exactly one identifier; `cnvContactId` takes precedence when both are provided.

When looking up by `email`, the most recently updated contact with that email address is returned.

> **Request access.** This endpoint is not enabled by default, contact the Conversion team to request access. Calls from accounts without it return `403 export_not_enabled`.



## OpenAPI

````yaml /openapi.json get /v2/contacts
openapi: 3.1.0
info:
  title: Conversion API
  version: 2.0.0
  description: >-
    The Conversion API lets you programmatically manage contacts, track custom
    events, and manage their associated data.
servers:
  - url: https://pub-api.conversion.ai/api
security:
  - apiKey: []
paths:
  /v2/contacts:
    get:
      summary: Get Contact
      description: >-
        Fetch a single contact by `email` or `cnvContactId`. Provide exactly one
        identifier; `cnvContactId` takes precedence when both are provided.


        When looking up by `email`, the most recently updated contact with that
        email address is returned.


        > **Request access.** This endpoint is not enabled by default, contact
        the Conversion team to request access. Calls from accounts without it
        return `403 export_not_enabled`.
      operationId: getContact
      parameters:
        - name: email
          in: query
          required: false
          schema:
            type: string
            format: email
          description: >-
            The contact's email address. When multiple contacts share the same
            email, the most recently updated contact is returned.
          examples:
            example:
              value: jane@example.com
        - name: cnvContactId
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: The Conversion contact ID.
          examples:
            example:
              value: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      responses:
        '200':
          description: Contact retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                      - contact
                    properties:
                      contact:
                        $ref: '#/components/schemas/Contact'
              examples:
                found:
                  summary: Contact found
                  value:
                    data:
                      contact:
                        cnvContactId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                        email: jane@example.com
                        userId: user_12345
                        subscriptionStatus: SUBSCRIBED
                        fields:
                          first_name: Jane
                          last_name: Smith
                          job_title: VP of Marketing
                        createdAt: '2026-01-10T08:00:00Z'
                        updatedAt: '2026-02-03T14:22:05Z'
        '400':
          description: The request was malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing-identifier:
                  summary: Missing identifier
                  value:
                    error:
                      code: missing_identifier
                      message: at least one of email or cnvContactId is required
                invalid-email:
                  summary: Invalid email
                  value:
                    error:
                      code: invalid_email
                      message: 'invalid email format: not-an-email'
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  summary: Missing or invalid API key
                  value:
                    error:
                      code: unauthorized
                      message: API key is required
        '403':
          description: This endpoint is not enabled for this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not-enabled:
                  summary: Endpoint not enabled
                  value:
                    error:
                      code: export_not_enabled
                      message: business is not authorized to use this endpoint
        '404':
          description: The contact was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                contact-not-found:
                  summary: Contact not found
                  value:
                    error:
                      code: contact_not_found
                      message: no contact found matching the provided identifier
        '500':
          description: An unexpected server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                internal:
                  summary: Internal error
                  value:
                    error:
                      code: internal_error
                      message: failed to get contact
components:
  schemas:
    Contact:
      type: object
      required:
        - cnvContactId
        - fields
        - createdAt
        - updatedAt
      properties:
        cnvContactId:
          type: string
          format: uuid
          description: The Conversion contact ID.
        email:
          type:
            - string
            - 'null'
          format: email
          description: The contact's email address, or `null` when not set.
        userId:
          type:
            - string
            - 'null'
          description: An external user identifier for the contact, or `null` when not set.
        subscriptionStatus:
          $ref: '#/components/schemas/SubscriptionStatus'
        fields:
          $ref: '#/components/schemas/ContactFields'
        createdAt:
          type: string
          format: date-time
          description: When the contact was created.
        updatedAt:
          type: string
          format: date-time
          description: When the contact was last updated.
    Error:
      type: object
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: A machine-readable error code.
              examples:
                - invalid_email
            message:
              type: string
              description: A human-readable error description.
              examples:
                - 'invalid email format: not-an-email'
    SubscriptionStatus:
      type: string
      enum:
        - SUBSCRIBED
        - UNSUBSCRIBED
        - NO_STATUS
      description: >-
        The contact's email subscription status. System-managed statuses
        (`BOUNCED`, `COMPLAINED`, etc.) cannot be set through the API.
    ContactFields:
      type: object
      additionalProperties: {}
      description: >-
        A map of contact field keys to values. Keys must match existing field
        definitions in your Conversion account.
      examples:
        - first_name: Jane
          last_name: Smith
          job_title: VP of Marketing
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your Conversion API key. Found in **Settings > Integrations** in the
        dashboard. Format: `sk_live_<key_id>_<secret>`.

````