Skip to main content

​
Get Contact by ID

This endpoint retrieves detailed information about a specific contact by its unique identifier.

​
Endpoint Details

  • URL: /contacts/{id}
  • Method: GET
  • Authentication: Required (API KEY or JWT Token)
  • Source: src/api/public_apis_v1/contact/contact_by_id/contact_by_id_controller.rs

​
Path Parameters

ParameterTypeRequiredDescriptionExample
idUUIDYesThe unique identifier of the contact to retrieve550e8400-e29b-41d4-a716-446655440000

​
Request Headers

HeaderValueDescription
AuthorizationBearer <api_key>Your API KEY or JWT Token
Content-Typeapplication/jsonRequest content type

​
Example Request

​
cURL

curl -X GET "https://api.callab.ai/contacts/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
JavaScript

const getContact = async (contactId) => {
  const url = `https://api.callab.ai/contacts/${contactId}`;
  const apiKey = 'YOUR_API_KEY';

  try {
    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }

    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error fetching contact:', error);
    throw error;
  }
};

// Usage
const contactId = '550e8400-e29b-41d4-a716-446655440000';
getContact(contactId).then(data => console.log(data));

​
Python

import requests

def get_contact(contact_id, api_key):
    url = f"https://api.callab.ai/contacts/{contact_id}"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    response = requests.get(url, headers=headers)

    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Error: {response.status_code} - {response.text}")

# Usage
contact_id = "550e8400-e29b-41d4-a716-446655440000"
api_key = "YOUR_API_KEY"
contact_data = get_contact(contact_id, api_key)
print(contact_data)

​
Response

​
Success Response

Status Code: 200 OK 
{
  "status": "ok",
  "message": "ok",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "company_id": "047efb70-8d78-4c6a-a9bf-0466739cf96a",
    "firstname": "John",
    "lastname": "Doe",
    "phone_number": "+1234567890",
    "metadata": {
      "email": "[email protected]",
      "company_name": "Acme Corp",
      "job_title": "Marketing Director",
      "property_interest": "3 bedroom apartments",
      "source": "website",
      "custom_field": "custom_value"
    },
    "number_country_code": "+1",
    "last_call_status": "completed",
    "last_call_at": "2024-01-15T14:30:00Z",
    "last_call_duration": 180,
    "last_call_feedback": "Customer was very interested in our services",
    "source_name": "Website Form",
    "tag_name": "hot_lead",
    "category_name": "sales_qualified",
    "notes": "Follow up next week regarding premium package",
    "created_at": "2024-01-10T09:00:00Z",
    "updated_at": "2024-01-15T14:32:00Z",
    "campaign_id": "650e8400-e29b-41d4-a716-446655440001",
    "status": "active",
    "workspace_id": "default"
  }
}

​
Error Response

Status Code: 200 OK (with error status) When a contact is not found or an error occurs: 
{
  "status": "error",
  "message": "error",
  "data": ""
}

​
Response Fields

FieldTypeDescription
idUUIDUnique identifier for the contact
company_idUUIDCompany that owns this contact
firstnameStringContact’s first name
lastnameStringContact’s last name
phone_numberStringContact’s phone number in E.164 format
metadataObject or nullCustom metadata fields (email, company, job title, etc.)
number_country_codeStringCountry code of the phone number (e.g., “+1”, “+44”)
last_call_statusStringStatus of most recent call (completed, busy, no-answer, in-progress)
last_call_atDateTime or nullTimestamp of the last call made to this contact
last_call_durationInteger or nullDuration of last call in seconds
last_call_feedbackString or nullFeedback from the most recent call
source_nameStringSource where contact was acquired (Manual, CSV Import, Website, etc.)
tag_nameStringTag label for categorization (hot_lead, cold_lead, etc.)
category_nameStringCategory classification (sales_qualified, marketing_qualified, etc.)
notesString or nullAdditional notes about the contact
created_atDateTimeTimestamp when contact was created
updated_atDateTimeTimestamp when contact was last updated
campaign_idUUID or nullAssociated campaign identifier if contact is in a campaign
statusStringContact status (active, inactive, deleted)
workspace_idStringWorkspace identifier (e.g., “default”, “production”)

​
Metadata Field

The metadata field is a flexible JSON object that can contain any custom fields. Common fields include:
FieldTypeDescription
emailStringContact’s email address
company_nameStringCompany or organization name
job_titleStringContact’s job title or role
property_interestStringFor real estate: type of property interested in
sourceStringSpecific source within the source_name (e.g., “landing_page”, “facebook_ad”)
custom_fieldAnyAny additional custom fields your business requires
The metadata field accepts any valid JSON structure and is not limited to the fields listed above.

​
Use Cases

​
1. Contact Details Retrieval

Fetch complete information about a specific contact for display in your CRM or application.

​
2. Pre-Call Context

Retrieve contact details before making a call to provide agents with customer context.

​
3. Contact Verification

Verify contact information and check their call history before adding to a new campaign.

​
4. CRM Integration

Sync contact data between Callab AI and your external CRM system using the contact ID.

​
5. Lead Qualification

Review contact metadata, tags, and categories to assess lead quality and prioritization.

​
6. Call History Review

Check the last call status, duration, and feedback to inform follow-up strategies.

​
Notes

  • The endpoint returns a standard success response even when the contact is not found (with error status)
  • All timestamps are returned in UTC format
  • The metadata field is flexible and can contain any custom JSON data your business requires
  • The last_call_status field will be null if no calls have been made to this contact yet
  • The campaign_id will be null if the contact is not currently assigned to any campaign
  • Phone numbers are stored in E.164 format but the API accepts various formats on input
  • The workspace_id allows for multi-tenant or environment-specific contact management
  • Tags and categories help organize and segment contacts for targeted campaigns
  • The source_name field tracks where the contact originated from for attribution purposes