> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clado.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# API Changelog
> Breaking changes and migration guide for the Clado Search & Enrichment API
## \[October 2025] - Legacy Format Deprecation Notice + Realtime Data
**BREAKING CHANGE**: The legacy response format will be deprecated on **November 1st, 2025**.
The modern format is significantly more complex with 97+ profile fields, nested models, and detailed type safety. Review the full type definitions before migrating.
### 🚀 New: Realtime Data Updates
All API endpoints now return **realtime data**:
* Profile information is continuously updated
* Company details reflect current status
* Engagement metrics (connections, followers, posts) are live
* Experience changes are tracked and identified in real-time
* No more stale data - always get the most current information available
### Affected Endpoints
* `GET /api/search` - Search People
* `GET /api/search/deep_research/{job_id}` - Get Deep Research Status
* `GET /api/enrich/linkedin` - Get LinkedIn Profile
***
## Migration Complexity Warning
The modern format contains **significantly more data** than the legacy format. A single profile response can include:
* **97 profile fields** (vs 10-15 in legacy)
* **48 experience fields per job** (vs 10-15 in legacy)
* **Complex nested objects** for breakdowns and change tracking
* **Detailed company information** including financials, stock data, geographic details
* **Structured date fields** with separate year/month instead of formatted strings
* **Type-safe arrays** instead of string representations
**Plan accordingly** - your parsing logic will need significant updates.
***
## Implementation Details
### Response Format Migration
The API supports both formats during the transition period:
* **Default (Modern)**: Full type-safe models with extensive data
* **Legacy**: Simplified format using transformation functions
* **Migration Period**: Both formats supported until November 1st, 2025
***
## Complete Modern Response Example
```json theme={null}
{
"results": [
{
// Basic Identity (10 fields)
"id": "123456789",
"name": "John Doe", // Legacy compatibility
"full_name": "John Michael Doe", // Primary modern field
"first_name": "John",
"first_name_initial": "J",
"middle_name": "Michael",
"middle_name_initial": "M",
"last_name": "Doe",
"last_name_initial": "D",
// Professional Info (3 fields)
"headline": "Senior Software Engineer at TechCorp Inc",
"description": "Experienced software engineer specializing in ML",
"summary": "Full professional summary with detailed background...",
// Profile Images (2 fields)
"picture_permalink": "https://static.licdn.com/aero-v1/sc/h/9c8pery4andzj6ohjkjp54ma2",
"picture_url": "https://static.licdn.com/aero-v1/sc/h/9c8pery4andzj6ohjkjp54ma2",
// Location Breakdown (8 fields)
"location": "San Francisco, CA", // Legacy compatibility
"location_full": "San Francisco, California, United States",
"location_country": "United States",
"location_city": "San Francisco",
"location_state": "California",
"location_country_iso2": "US",
"location_country_iso3": "USA",
"location_regions": ["Americas", "Northern America", "AMER"],
// LinkedIn Data (2 fields)
"linkedin_url": "https://www.linkedin.com/in/johndoe",
"linkedin_shorthand_names": ["johndoe"],
// Engagement Metrics (5 fields)
"connections_count": 500,
"followers_count": 1200,
"post_count": 15,
"posts": "Recent posts content as concatenated string...",
"liked_posts": "Liked posts content as concatenated string...",
"recommendations": "Recommendations as concatenated string...",
"recommendations_count": 8,
// Work Status (3 fields)
"is_working": 1, // 0/1 or true/false
"is_decision_maker": 0, // 0/1 or true/false
"total_experience_duration_months": 48,
// Experience Breakdowns (2 complex arrays)
"total_experience_duration_months_breakdown_department": [
{
"department": "Engineering and Technical",
"management_level": null,
"total_experience_duration_months": 48
}
],
"total_experience_duration_months_breakdown_management_level": [
{
"department": null,
"management_level": "Senior",
"total_experience_duration_months": 24
}
],
// Active Experience Details (5 fields)
"active_experience_company_id": 12345,
"active_experience_title": "Senior Software Engineer",
"active_experience_description": "Working on ML systems...",
"active_experience_department": "Engineering and Technical",
"active_experience_management_level": "Senior",
// Skill Categories (5 fields)
"skills": ["Python", "JavaScript", "Machine Learning"],
"inferred_skills": ["Python", "ML", "Data Science"],
"historical_skills": ["Java", "C++", "PHP"],
"interests": ["AI", "Machine Learning", "Distributed Systems"],
"services": "Consulting, Development, Technical Leadership",
// Education Summary (2 fields)
"last_graduation_date": 2022,
"education_degrees": ["Computer Science", "MBA"],
// Salary Projections (16 fields!)
"projected_total_salary": 150000.0,
"projected_base_salary_p25": 120000.0,
"projected_base_salary_median": 140000.0,
"projected_base_salary_p75": 160000.0,
"projected_base_salary_period": "ANNUAL",
"projected_base_salary_currency": "USD",
"projected_base_salary_updated_at": "2024-01-01",
"projected_additional_salary_period": "ANNUAL",
"projected_additional_salary_currency": "USD",
"projected_additional_salary_updated_at": "2024-01-01",
"projected_total_salary_p25": 130000.0,
"projected_total_salary_median": 150000.0,
"projected_total_salary_p75": 170000.0,
"projected_total_salary_period": "ANNUAL",
"projected_total_salary_currency": "USD",
"projected_total_salary_updated_at": "2024-01-01",
"projected_additional_salary": [
{
"projected_additional_salary_type": "Bonus",
"projected_additional_salary_p25": 10000.0,
"projected_additional_salary_median": 15000.0,
"projected_additional_salary_p75": 20000.0
}
],
// Content Statistics (6 fields)
"patents_count": 2,
"patents_topics": ["AI", "Machine Learning"],
"publications_count": 5,
"publications_topics": ["Software Engineering", "AI"],
"projects_count": 3,
"projects_topics": ["Web Development", "ML"],
// Metadata Timestamps (7 fields)
"created_at": "2023-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"checked_at": "2024-01-01T00:00:00Z",
"changed_at": "2024-01-01T00:00:00Z",
"experience_change_last_identified_at": "2024-01-01T00:00:00Z",
"op_created_at": "2023-01-01T00:00:00Z",
"op_updated_at": "2024-01-01T00:00:00Z",
// Change Tracking Arrays (4 complex arrays)
"profile_root_field_changes_summary": [
{
"field_name": "headline",
"change_type": "updated",
"last_changed_at": "2024-01-01T00:00:00Z"
}
],
"profile_collection_field_changes_summary": [
{
"field_name": "experience",
"last_changed_at": "2024-01-01T00:00:00Z"
}
],
"experience_recently_started": [
{
"company_id": 12345,
"company_name": "TechCorp",
"company_url": "https://techcorp.com",
"company_shorthand_name": "techcorp",
"date_from": "2024-01",
"date_to": null,
"title": "Senior Software Engineer",
"identification_date": "2024-01-01T00:00:00Z"
}
],
"experience_recently_closed": [],
"experience": [
{
// Position Details (6 fields)
"active_experience": 1, // 0 or 1
"position_title": "Senior Software Engineer",
"department": "Engineering and Technical",
"management_level": "Senior",
"location": "San Francisco, CA",
"description": "Working on ML systems and distributed architecture...",
// Date Information (7 fields)
"date_from": "January 2022", // Human readable
"date_from_year": 2022, // Separate integer fields
"date_from_month": 1,
"date_to": null, // Null for current
"date_to_year": null,
"date_to_month": null,
"duration_months": 24, // Pure integer
// Company Basic Info (4 fields)
"company_id": 12345, // Pure integer
"company_name": "TechCorp Inc",
"company_type": "Privately Held",
"company_founded_year": 2010,
// Company Engagement (2 fields)
"company_followers_count": 500,
"company_website": "https://techcorp.com",
// Company Social Media (4 fields)
"company_facebook_url": "https://facebook.com/techcorp", // Can be string or array
"company_twitter_url": ["https://twitter.com/techcorp"],
"company_professional_network_url": null,
"company_linkedin_url": "https://linkedin.com/company/techcorp",
// Company Size & Industry (4 fields)
"company_size_range": "201-500 employees",
"company_employees_count": 350,
"company_industry": "Software Development",
"company_categories_and_keywords": ["software", "technology", "saas"],
// Company Financials (6 fields)
"company_annual_revenue_source_1": 50000000.0,
"company_annual_revenue_currency_source_1": "USD",
"company_annual_revenue_source_5": 50000000,
"company_annual_revenue_currency_source_5": "USD",
"company_employees_count_change_yearly_percentage": 15.5,
"company_last_funding_round_date": "2023-01-01",
"company_last_funding_round_amount_raised": 10000000,
// Company Geographic Details (9 fields)
"company_hq_full_address": "123 Main St, San Francisco, CA 94105, US",
"company_hq_country": "United States",
"company_hq_regions": ["Americas", "Northern America", "AMER"],
"company_hq_country_iso2": "US",
"company_hq_country_iso3": "USA",
"company_hq_city": "San Francisco",
"company_hq_state": "California",
"company_hq_street": "123 Main St",
"company_hq_zipcode": "94105",
// Company Metadata (4 fields)
"company_last_updated_at": "2024-01-01",
"company_stock_ticker": [
{
"exchange": "NASDAQ",
"ticker": "TECH"
}
],
"company_is_b2b": 1, // 0 or 1
"order_in_profile": 1
}
],
"education": [
{
// Basic Education (3 fields)
"degree": "Master of Science",
"description": "Focus on Machine Learning and Distributed Systems",
"institution_url": "https://university.edu",
"institution_name": "State University",
// Institution Geographic Details (9 fields)
"institution_full_address": "456 University Ave, Berkeley, CA 94720, US",
"institution_country_iso2": "US",
"institution_country_iso3": "USA",
"institution_regions": ["Americas", "Northern America", "AMER"],
"institution_city": "Berkeley",
"institution_state": "California",
"institution_street": "456 University Ave",
"institution_zipcode": "94720",
// Education Timeline (2 fields)
"date_from_year": 2017,
"date_to_year": 2019,
// Additional Info (2 fields)
"activities_and_societies": "Computer Science Club, AI Research Group",
"order_in_profile": 1
}
],
"languages": [
{
"language": "English",
"proficiency": "Native",
"order_in_profile": 1
},
{
"language": "Spanish",
"proficiency": "Professional",
"order_in_profile": 2
}
],
"awards": [
{
"title": "Employee of the Year",
"issuer": "TechCorp Inc",
"description": "Outstanding contribution to ML infrastructure",
"date_year": 2023,
"date_month": 12,
"order_in_profile": 1
}
],
"certifications": [
{
"title": "AWS Solutions Architect",
"issuer": "Amazon Web Services",
"date_from_year": 2022,
"date_from_month": 6,
"date_to_year": 2025,
"date_to_month": 6
}
],
"organizations": [
{
"organization_name": "IEEE Computer Society",
"position": "Member",
"description": "Active member participating in ML conferences",
"date_from_year": 2020,
"date_from_month": 1,
"date_to_year": null,
"date_to_month": null
}
],
"patents": [
{
"title": "Distributed Machine Learning System",
"description": "Method for optimizing ML training across distributed nodes",
"status": "Granted",
"date_year": 2023,
"date_month": 8
}
],
"projects": [
{
"name": "ML Infrastructure Platform",
"description": "Built scalable ML training and inference platform",
"date_from_year": 2022,
"date_from_month": 1,
"date_to_year": 2023,
"date_to_month": 12
}
],
"publications": [
{
"title": "Optimizing Distributed ML Training",
"description": "Research on improving efficiency of distributed machine learning",
"publisher_names": ["IEEE Transactions on Parallel and Distributed Systems"],
"date_year": 2023,
"date_month": 3
}
],
"github_repos": [
{
"name": "ml-distributed-trainer",
"summary": "Open source distributed ML training framework",
"stars": 245,
"contributions_count": 156
}
],
"courses": [
{
"organizer": "Stanford University",
"title": "Advanced Machine Learning",
"order_in_profile": 1
}
],
"match_data": {
"similarity_score": 0.95,
"matched_criteria": ["machine learning", "senior engineer", "python"]
}
}
],
"total": 1,
"query": "senior machine learning engineers at tech companies",
"search_id": "550e8400-e29b-41d4-a716-446655440000"
}
```
**Field Count Summary (per result object):**
* **Root-level fields**: 97 fields across all categories (identity, professional info, location, engagement, work status, skills, salary projections, content statistics, metadata, change tracking)
* **Experience array**: 48 fields per job including 30+ company-specific fields
* **Education array**: 15 fields including detailed institution geography
* **Plus**: Languages, Awards, Certifications, Organizations, Patents, Projects, Publications, GitHub repos, Courses
***