Get Contact Info

Endpoint

GET /contacts/{contact_id}
Base URL: https://api.example-ai.com/v1

Description

Retrieve detailed information about a contact, including primary phone number, email, and tags.
Use this to display contact profiles, enrich call logs, or personalize AI interactions.

Authentication

Authorization: Bearer sk_test_51_fakeapikey123456

Headers

Header	Type	Required	Description
Authorization	string	Yes	Bearer <token>
Content-Type	string	No	application/json

Request Parameters

Path Parameters

Name	Type	Required	Description
contact_id	string	Yes	Contact ID, e.g. ctc_12kd88.

Query Parameters

Name	Type	Required	Description
include_meta	boolean	No	Whether to include extended metadata. Default: false.

Example Request

curl

curl -X GET "https://api.example-ai.com/v1/contacts/ctc_12kd88?include_meta=true" \
  -H "Authorization: Bearer sk_test_51_fakeapikey123456" \
  -H "Content-Type: application/json"

Example Response

{
  "status": "success",
  "message": "Contact retrieved successfully.",
  "data": {
    "id": "ctc_12kd88",
    "external_id": "crm_9982",
    "full_name": "Alex Johnson",
    "primary_phone": "+1-415-555-0199",
    "primary_email": "alex.johnson@example.com",
    "timezone": "America/Los_Angeles",
    "tags": ["vip", "renewal-2026"],
    "metadata": {
      "billing_tier": "enterprise",
      "account_manager_id": "usr_44ks01"
    },
    "created_at": "2025-11-02T10:11:45Z",
    "updated_at": "2026-03-15T14:18:03Z"
  }
}

Error Responses

400 Bad Request

{
  "status": "error",
  "message": "Invalid contact_id format.",
  "data": null
}

401 Unauthorized

{
  "status": "error",
  "message": "Unauthorized.",
  "data": null
}

404 Not Found

{
  "status": "error",
  "message": "Contact not found: ctc_12kd88.",
  "data": null
}

500 Server Error

{
  "status": "error",
  "message": "Unexpected error while loading contact.",
  "data": null
}

Code Examples

curl

curl -X GET "https://api.example-ai.com/v1/contacts/ctc_12kd88" \
  -H "Authorization: Bearer sk_test_51_fakeapikey123456"

JavaScript (fetch)

const response = await fetch(
  'https://api.example-ai.com/v1/contacts/ctc_12kd88',
  {
    headers: {
      Authorization: 'Bearer sk_test_51_fakeapikey123456'
    }
  }
);

const result = await response.json();
console.log(result.data.full_name);

TypeScript (axios)

import axios, { AxiosResponse } from 'axios';

interface Contact {
  id: string;
  external_id?: string;
  full_name: string;
  primary_phone?: string;
  primary_email?: string;
  timezone?: string;
  tags: string[];
  metadata?: Record<string, unknown>;
  created_at: string;
  updated_at: string;
}

interface ContactResponse {
  status: 'success' | 'error';
  message: string;
  data: Contact | null;
}

const res: AxiosResponse<ContactResponse> = await axios.get(
  'https://api.example-ai.com/v1/contacts/ctc_12kd88',
  {
    headers: {
      Authorization: 'Bearer sk_test_51_fakeapikey123456'
    }
  }
);

console.log(res.data.data?.primary_phone);

Notes

• external_id can be used to link this contact to your internal CRM or billing system.
• Use tags to drive routing, prioritization, or AI prompt customization.