Docs index

Data dictionary

Shared request/response field definitions and object models.

Context guidance: Use when interpreting response object shapes such as profiles, jobs, companies, and chunks.

Data dictionary

Full model and field definitions are available in /docs/data-dictionary.json.

Notes

  • Fields marked optional may be omitted. Unknown fields can appear as the schema evolves.
  • Search responses include the internal person object plus normalized top-level fields when available.
  • Use description for natural-language searches; query is a legacy alias. The text is auto-translated into AdvancedFilters by default. Use filters/search_metadata to supply explicit structured constraints.
  • Direct LinkedIn lookup accepts linkedin_username (vanity), linkedin_profile_url, or linkedin_url. Use the profile URL path when your upstream workflow already has full LinkedIn URLs.
  • Search rows with evidence_format=json already include declarative evidence for alignment to requested filters. Direct LinkedIn lookup and batch direct lookup are for loading the latest available Super Carl profile data for known LinkedIn identities, not for independent certification of identity or employment; do not describe lookup as verifying or confirming employment.
  • If a row lacks a LinkedIn identity or lookup cannot resolve, do not recover with broad keyword-only people search. Re-resolve the employer with company search, then run people search with company_search_id binding plus companies.include_current_only=true and job_titles.current_only=true; ask for disambiguation when the company cannot be resolved confidently.
  • If you send keywords, they are merged into filters.additional_context. Prefer filters.additional_context (or additional_context_keywords) instead.
  • Resolved filters (including description translation) are echoed back in search_metadata.filters.advanced.
  • Set include_evidence_text=true on people search/preview/enrich to inline aggregated profile evidence text, or include_evidence_json=true for structured evidence. evidence_format=text|json|both is shorthand; evidence_format=reasons opts into deterministic light match_reasons on full people searches. For large preview-row paging, use preview + skip_match_reasons=true / evidence_format=none. evidence_text_mode=base returns compact embedding-ready text; evidence_text_mode=full adds company and recent-post context.
  • People-search responses can include requester-relative social proximity summary fields on each Person row. Detailed evidence and connector-path payloads are documented in the Social proximity section and authenticated user models below.
  • When a search returns zero results due to insufficient persona profile context, search_metadata.no_results_reason and no_results_reason_code can explain why.
  • Company search previews return search_id values that can be used in filters.companies.include_company_search_id/exclude_company_search_id for people searches. If a company search resolves to more than 10k companies, the top-ranked 10k companies are applied and surfaced as capped in search_metadata.company_search_filters.
  • Company search responses include company_resolution with status=resolved|ambiguous|unresolved|set, a deduplicated candidates[] (collapsed by linkedin_slug → domain → normalized name), candidate_count (deduped), raw_candidate_count (pre-dedupe), and a brand_name_match boolean. Proceed to people_search when status=resolved. Treat status=ambiguous or unresolved as needing a domain/LinkedIn URL or user selection before binding a people search; status=unresolved with reason=no_brand_name_match means the resolver returned hits but none overlapped the queried brand, which is the right time to ask for the canonical URL. For descriptor/set searches, status=set means the search_id is intentionally a company set.
  • Company search preview supports result_mode=preview|detailed and a resolve_only=true flag. resolve_only drops the companies[] array entirely and returns just company_resolution + search_id — use it for cheap named-company disambiguation passes when iterating over a brand list. Detailed mode expands each company row with canonical URLs, funding/stage metadata, and optional evidence_text built from stored company records and recent posts.
  • Public docs also publish static corpus and refresh-cadence metadata in data_scale so agent integrations can plan around dataset shape without hitting expensive live stats.
  • Use GET /api/v1/credits to inspect the shared account credit pool, current-key usage counters, live search rate card, and operation-level billing semantics.
  • Use GET /api/v1/credits/status for a lightweight rolling-window status (tier, limit, used, remaining, reset_at). Every authenticated response also carries X-Carl-Credits-* headers with the same values. See credit_enforcement in this schema for the full policy, the 402 credits_exhausted body, and the MCP over-limit structured result.
  • Communications are exposed as non-assignment communication records with normalized status, events, webhook delivery metadata, and artifact links.
  • Projects are the public API name for assignment workspaces. Project endpoints expose the same target list, response metrics, template update, template generation, and personalized-message generation operations used by product flows.
  • Company search numeric ranges accept either numbers or shorthand strings (examples: 500K, 25M, 1.2B).
  • AdvancedFilters fields below are generated from the backend canonical schema used by preview/search tools to avoid drift.

Models

  • CreditsResponse (12 fields) - Response payload from GET /api/v1/credits.
  • CreditStatusResponse (8 fields) - Response from GET /api/v1/credits/status and GET /users/me/credits/status. Mirrors the X-Carl-Credits-* response headers.
  • CreditsExhaustedError (9 fields) - HTTP 402 response body returned when the account owner is at or over the credit ceiling and CREDIT_ENFORCEMENT_ENABLED is on.
  • CreditsAnnotation (5 fields) - Block appended to structuredContent on every successful MCP tool response so clients can render balance hints.
  • McpCreditsExhaustedError (12 fields) - Handled MCP result returned when the account owner is at or over the credit ceiling. It stays on the normal result path so hosts preserve the structured credit metadata instead of promoting it to an opaque runtime exception.
  • CurrentApiKey (7 fields) - Authenticated API key metadata returned by GET /api/v1/credits.
  • CurrentApiKeyUsage (5 fields) - Recorded search credit-event counters for one API key.
  • CreditPoolTotals (4 fields) - Account-level totals for the shared credit pool.
  • CreditUsageBreakdownEntry (7 fields) - Breakdown row for account_credit_pool.breakdown.
  • CreditConversionRule (7 fields) - Active conversion rule relevant to the public API.
  • CreditCostRate (8 fields) - Active internal cost rate relevant to the public API.
  • CreditBillingSemanticsEntry (7 fields) - Billing behavior for one public API operation.
  • CommunicationChannelCapability (6 fields) - Per-channel sendability record returned by POST /api/v1/communications/capabilities.
  • CommunicationEvent (10 fields) - Append-only event emitted for a communication lifecycle.
  • CommunicationTask (4 fields) - Linked task summary when the communication is backed by async work.
  • CommunicationReasoningLookup (4 fields) - Lookup payload for related reasoning context.
  • CommunicationArtifact (3 fields) - Communication artifact metadata, usually backed by a browser screenshot.
  • CommunicationWebhook (5 fields) - Request-scoped webhook delivery summary stored on a communication.
  • Communication (19 fields) - Generic non-assignment communication record returned by the communications API.
  • Project (18 fields) - Public API name for a Super Carl assignment workspace. Older internal fields may still use assignment/campaign names.
  • ProjectTarget (12 fields) - Included target row in a Super Carl project.
  • ProjectMetrics (11 fields) - Response metrics returned by GET /api/v1/projects/:projectId/metrics.
  • SearchRequest (26 fields) - Payload for /api/v1/search/people and /api/v1/search/people/preview.
  • SearchResponse (11 fields) - Response from full or preview search requests.
  • ViewerNetworkState (7 fields) - Compact snapshot of the calling user's integration state. The "synced data" facet (linkedin_sync_data) governs what network/worked-with/shared-school/reachability filters can be applied; the "session" facet (linkedin_session) governs live LinkedIn actions like send-message and accept-invite. The two are independent: a user can search their synced 1st-degree network even with an expired session.
  • LinkedinSyncData (6 fields) - Synced LinkedIn snapshot stats. Network-degree, worked-with, shared-school, and reachability filters read this — search works whenever available is true, even if the live session has expired.
  • NetworkDegreeScope (2 fields) - Coverage contract for requester-relative degree fields and job/company network overlays.
  • SecondDegreeScope (12 fields) - Super Carl 2nd-degree coverage derived through claimed Super Carl Connectors that have shared their networks.
  • LinkedinSession (4 fields) - Live LinkedIn browser session held by the extension. Required only for live actions (send message, accept invite, fresh scrape, continue sync). Does NOT gate search.
  • SuperCarlNetworkSummary (1 fields) - Super Carl claimed-invite graph counts.
  • GmailIntegrationSummary (2 fields) - Gmail integration state.
  • Pagination (4 fields) - Pagination details for result sets.
  • Person (51 fields) - Primary person record returned by searches, including requester-relative reachability and social proximity summary fields when available.
  • PersonSummary (4 fields) - Compact person summary used for mutual connections.
  • MatchedCurrentExperience (6 fields) - Details about the role used for current title/company display.
  • MatchedRoleExperience (6 fields) - Optional matched role evidence that can represent a historical role.
  • ProfileSnapshot (10 fields) - Response from /api/v1/profiles/:id.
  • ProfileChunksResponse (3 fields) - Response from /api/v1/profiles/:id/chunks.
  • ProfileChunk (7 fields) - Structured chunk describing profile experiences, education, or posts.
  • ExperienceChunkMetadata (20 fields) - Structured metadata for experience chunks returned by /api/v1/profiles/:id/chunks.
  • EducationChunkMetadata (8 fields) - Structured metadata for education chunks.
  • PostChunkMetadata (9 fields) - Structured metadata for post and repost chunks.
  • ProfileText (4 fields) - Profile text payload for /api/v1/profiles/:id/text.
  • JobNetworkOverlayStatus (10 fields) - Readiness and scope for per-job viewer-network counts. A zero is conclusive only when status is ready and zero_counts_are_conclusive is true; unavailable means unknown.
  • JobPosting (29 fields) - Job posting row returned by /api/v1/search/jobs/preview. Each row is decorated with a network block summarizing 1st/2nd-degree connections at the posting company.
  • JobsWithPeopleGroup (4 fields) - One company bucket returned by /api/v1/search/jobs/with-people, pairing matching jobs with the viewer's 1st/2nd-degree people at that company.
  • ActivityPost (17 fields) - Post/activity row returned by /api/v1/search/posts/preview and /api/v1/search/posts/with-people.
  • PostMatchedPerson (10 fields) - Deduped person row derived from matching ActivityPost actors/authors.
  • PostMatchedCompany (12 fields) - Deduped company row derived only from matching official company-authored ActivityPost rows. This is an observed-actor join; exact canonical identity is labeled and unresolved actors remain explicit.
  • SearchMetadata (12 fields) - Search context and applied filters.
  • SocialProximityEvidence (3 fields) - Deduped evidence item returned by authenticated social-proximity endpoints.
  • SocialProximityComponents (8 fields) - Component-level score breakdown stored in summary.metadata.components.
  • SocialProximitySummary (20 fields) - Authenticated requester-relative social proximity summary for one target.
  • SocialProximitySummaryEntry (2 fields) - Entry returned by POST /users/social-proximity/summaries for one target user.
  • SocialProximitySummaryResponse (3 fields) - Response payload from POST /users/social-proximity/summaries.
  • SocialProximityScoreCard (5 fields) - Compact baseline or researched score card returned by the detail endpoint.
  • SocialProximityConnector (16 fields) - Candidate mutual connector returned by the detail endpoint.
  • SocialProximityResearchStatus (17 fields) - LinkedIn mutual-research workflow status returned by the detail endpoint.
  • SocialProximityDetail (7 fields) - Response payload from GET /users/:targetUserId/social-proximity and POST /users/:targetUserId/social-proximity/research.
  • AdvancedFilters (45 fields) - Structured filters for search.
  • CompanySearchPreviewRequest (7 fields) - Payload for /api/v1/companies/search/preview.
  • CompanySearchFilters (18 fields) - Structured filters for company search previews. Numeric ranges accept number or shorthand string input.
  • CompanySearchPreviewCompany (29 fields) - Company row returned by company search. Preview mode returns the base fields; detailed mode adds the richer fields below.
  • CompanySearchPreviewResponse (5 fields) - Response payload for company search previews. companies[] rows vary by result_mode.
  • ErrorResponse (4 fields) - Standard error payload.

Machine-readable JSON