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

# Get a contact

> Read one live end-user record by its document ID.

A missing, deleted, merged, test or foreign record returns 404 not\_found.

## Related pages

* [Authentication](https://hellotars.com/docs/developer/authentication.md)


## OpenAPI

````yaml api-reference/openapi.json GET /api/v1/contacts/{id}
openapi: 3.1.0
info:
  title: Tars API
  version: '1'
  description: >-
    Start conversations, send messages, manage contacts, send campaign messages,
    place and read calls, and manage webhook destinations.
servers:
  - url: https://us.api.hellotars.com
    description: United States
  - url: https://eu.api.hellotars.com
    description: European Union
  - url: https://in.api.hellotars.com
    description: India
  - url: https://qa.api.hellotars.com
    description: Qatar
security:
  - bearerAuth: []
tags:
  - name: Conversations
    description: Start conversations at a chat agent's trigger step.
  - name: Messages
    description: Send channel messages as a chat agent.
  - name: Contacts
    description: Read and manage contacts.
  - name: Campaigns
    description: Send webhook campaign messages.
  - name: Calls
    description: Place, read and manage phone calls.
  - name: Agents
    description: Read chat agents and voice agents.
  - name: Phone numbers
    description: Read your phone numbers.
  - name: Artefacts
    description: Download call recordings.
  - name: Webhooks
    description: Manage webhook destinations.
paths:
  /api/v1/contacts/{id}:
    get:
      tags:
        - Contacts
      summary: Get a contact
      description: |-
        Reads one live contact.

        Requires the Read contacts permission (`contacts:read`).
      operationId: getContact
      parameters:
        - name: id
          in: path
          required: true
          description: The id.
          schema:
            type: string
            minLength: 1
            maxLength: 128
      responses:
        '200':
          description: The contact.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '400':
          description: validation_failed
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: unauthorized, invalid_key
          headers:
            WWW-Authenticate:
              schema:
                const: Bearer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: organization_inactive, billing_locked, permission_missing
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: not_found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '405':
          description: method_not_allowed
          headers:
            Allow:
              description: The methods this path accepts.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: wrong_region
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: rate_limited
          headers:
            Retry-After:
              description: Whole seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: internal_error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - bearerAuth: []
components:
  schemas:
    Contact:
      type: object
      description: A contact in your organization.
      properties:
        id:
          type: string
          description: The contact id.
        name:
          type: string
        email:
          type: string
          description: Email address, normalized.
        phone:
          type: string
          description: Phone number in E.164 format.
        tags:
          type: array
          items:
            type: string
        origin:
          type: string
          enum:
            - inbound
            - imported
            - manual
            - outbound_call
          description: >-
            How the contact was created: inbound from a conversation, imported
            from a file, manual by hand or over this API, outbound_call when a
            voice agent called the number.
        channelIdentifiers:
          $ref: '#/components/schemas/ChannelIdentifiers'
        consent:
          type: object
          description: Consent per channel, keyed by channel name such as web or whatsapp.
          additionalProperties:
            $ref: '#/components/schemas/ChannelConsent'
        createdAt:
          type: number
          description: When the contact was created, in milliseconds since the epoch.
        lastSeenAt:
          type: number
          description: When the contact was last active, in milliseconds since the epoch.
      required:
        - id
        - tags
        - origin
        - createdAt
        - lastSeenAt
    Problem:
      type: object
      description: >-
        RFC 9457 problem details. Clients switch on code, never on title or
        detail.
      properties:
        title:
          type: string
          description: The catalogue title of code.
        status:
          type: integer
          description: The HTTP status.
        detail:
          type: string
          description: A sentence about this failure, for a developer.
        instance:
          type: string
          description: The request id (req_…). Quote it when you contact support.
        code:
          type: string
          enum:
            - invalid_json
            - validation_failed
            - variable_key_not_allowed
            - invalid_variable_value
            - cursor_expired
            - cursor_mismatch
            - campaign_mode_invalid
            - unauthorized
            - invalid_key
            - session_invalid
            - insufficient_balance
            - organization_inactive
            - billing_locked
            - permission_missing
            - resource_not_allowed
            - entitlement_missing
            - origin_not_allowed
            - recaptcha_failed
            - consent_revoked
            - us_marketing_blocked
            - channel_test_mode
            - quota_exceeded
            - forbidden
            - not_found
            - method_not_allowed
            - wrong_region
            - conflict
            - contact_exists
            - idempotency_key_reuse
            - agent_unavailable
            - call_not_live
            - call_still_live
            - call_content_deleted
            - invalid_state
            - campaign_paused
            - template_version_drift
            - channel_unavailable
            - artefact_deleted
            - campaign_gone
            - payload_too_large
            - template_not_approved
            - channel_misconfigured
            - channel_reauth_required
            - meta_rejected
            - rate_limited
            - concurrency_limit_reached
            - worker_busy
            - meta_rate_limited
            - internal_error
            - upstream_unavailable
            - meta_unavailable
            - worker_not_deployed
            - worker_unavailable
        retryable:
          type: boolean
          description: true when the same request can succeed later.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationIssue'
        required:
          type: string
          description: The permission the key lacks (permission_missing).
        region:
          type: string
          description: The organization's region (wrong_region).
        field:
          type: string
          enum:
            - email
            - phone
        contactId:
          type: string
          description: The contact that already has the email or phone.
        callId:
          type: string
        reason:
          type: string
      required:
        - title
        - status
        - detail
        - instance
        - code
        - retryable
    ChannelIdentifiers:
      type: object
      description: >-
        Where Tars can reach the contact on each channel. Only the channels Tars
        has seen are present.
      properties:
        web:
          type: string
          description: The contact's web channel id.
        whatsapp:
          type: object
          description: The contact's WhatsApp identity.
          properties:
            phone:
              type: string
              description: Phone number in E.164 format, for example +15551234567.
            bsuid:
              type: string
              description: An alternate WhatsApp id of the contact.
    ChannelConsent:
      type: object
      description: Current consent on one channel, and how it got there.
      properties:
        optedIn:
          type: boolean
        timestamp:
          type: number
          description: When the current state was set, in milliseconds since the epoch.
        source:
          type: string
          enum:
            - csv_import
            - api
            - manual
            - organic
            - keyword
            - bounce
            - call
          description: What set the current state.
        history:
          type: array
          description: Every earlier change, oldest first.
          items:
            $ref: '#/components/schemas/ConsentHistoryEntry'
      required:
        - optedIn
        - timestamp
        - source
        - history
    ValidationIssue:
      type: object
      description: One field that failed validation.
      properties:
        path:
          type: string
          description: >-
            Dotted path of the field (template.parameters.body.0), the query
            parameter name, or an empty string for the whole body.
        code:
          type: string
          description: >-
            Why the field failed, for example required, unknown_field,
            out_of_range or template_param_missing.
        message:
          type: string
      required:
        - path
        - code
    ConsentHistoryEntry:
      type: object
      description: One recorded change of consent.
      properties:
        optedIn:
          type: boolean
          description: The consent after the change.
        timestamp:
          type: number
          description: When the change happened, in milliseconds since the epoch.
        source:
          type: string
          enum:
            - csv_import
            - api
            - manual
            - organic
            - keyword
            - bounce
            - call
          description: What caused the change.
        changedBy:
          type: string
          description: The member who made the change, when a person made it.
      required:
        - optedIn
        - timestamp
        - source
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key (`tars_sk_…`) sent as `Authorization: Bearer <key>`. Each
        operation names the permission it needs. Create keys in Settings →
        Integrations → API keys.

````

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