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

# Read Contact Data

> Read the stored data for a contact phone number

Use this endpoint to retrieve state that Simple or another connected system
previously stored for a caller. This lets a workflow such as Five9 look up
context from an earlier touch using the caller's phone number.

Data is scoped to your organization. US numbers can be formatted or sent as
digits. Non-US numbers must include the `+` country code. URL-encode the `+`
when it appears in the path.

```bash theme={null}
curl 'https://api.usesimple.ai/api/v1/contacts/%2B14155550100/data' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

The response includes the normalized phone number, stored object, revision,
and expiration metadata:

```json theme={null}
{
  "phoneNumber": "+14155550100",
  "data": {
    "five9ConversationId": "conv-48291",
    "routingStatus": "awaiting_follow_up"
  },
  "revision": 3,
  "ttlSeconds": null,
  "expiresAt": null
}
```

Records have no expiry by default. A record with an expired TTL, or a record
that has been deleted, is treated as missing and returns `404`.

The endpoint returns `401` when authentication fails, `404` when no current
data exists for the phone number, and `422` when the phone number is invalid.


## OpenAPI

````yaml GET /contacts/{phoneNumber}/data
openapi: 3.1.0
info:
  title: Public API v1
  description: >-
    Public API v1 requiring API keys.


    **Timestamps:** All datetime fields in API responses are returned in UTC
    using ISO 8601 format (e.g., `2024-01-15T14:30:00Z`). When filtering by date
    parameters, provide timestamps in ISO 8601 format.
  version: 0.1.0
servers:
  - url: https://api.prod.usesimple.ai/api/v1
    description: Production API Server
security: []
paths:
  /contacts/{phoneNumber}/data:
    get:
      tags:
        - Contacts
      summary: Read Contact Data
      description: >-
        Read the current JSON object stored for a phone number in the
        authenticated organization.
      operationId: read_contact_data_contacts__phoneNumber__data_get
      parameters:
        - name: phoneNumber
          in: path
          required: true
          schema:
            type: string
          description: >-
            The caller's phone number. US numbers may be formatted or sent as
            digits; non-US numbers must include the + country code.
      responses:
        '200':
          description: Current contact data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactDataResponse'
        '401':
          description: Authentication failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '404':
          description: No current data exists for this phone number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '422':
          description: The phone number is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    ContactDataResponse:
      type: object
      required:
        - phoneNumber
        - data
        - revision
        - ttlSeconds
        - expiresAt
      properties:
        phoneNumber:
          type: string
          description: The normalized phone number in E.164 format.
        data:
          type: object
          additionalProperties: true
          description: The stored JSON object.
        revision:
          type: integer
          minimum: 1
          description: The revision number of this value.
        ttlSeconds:
          anyOf:
            - type: integer
            - type: 'null'
          description: Remaining TTL in seconds, or null when the record has no expiry.
        expiresAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          description: Expiration timestamp in UTC, or null when the record has no expiry.
      title: Contact Data Response
    PublicApiError:
      type: object
      required:
        - status
        - success
        - error
        - errors
      properties:
        status:
          type: string
          const: error
        success:
          type: boolean
          const: false
        error:
          type: string
        errors:
          type: array
          items:
            type: string
      title: Public API Error
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization

````