@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/companies.d.ts

@@ -0,0 +1,1636 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.companies` (Companies): 50 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"assign_company_owner_companies_assign_owner_post">;
+ *
+ * Reference with examples: companies.md
+ */
+/* eslint-disable */
+
+/** `g8.api.companies.<member>` -> the operationId it calls. */
+export interface CompaniesMembers {
+  assignCompanyOwner: "assign_company_owner_companies_assign_owner_post";
+  attachCompanyContact: "attach_company_contact_companies__company_id__contacts__contact_id__post";
+  bulkEnrichCompanies: "bulk_enrich_companies_companies_enrich_bulk_post";
+  bulkEnrichCompanyPeople: "bulk_enrich_company_people_companies_enrich_people_bulk_post";
+  bulkEnrichCompanyStakeholders: "bulk_enrich_company_stakeholders_companies_enrich_stakeholders_bulk_post";
+  createCompany: "create_company_companies_post";
+  createCompanyColumn: "create_company_column_companies_columns_create_post";
+  createCompanyTask: "create_company_task_companies__company_id__tasks_post";
+  deleteCompany: "delete_company_companies__company_id__delete";
+  deleteCompanyColumn: "delete_company_column_companies_columns__column_id__delete";
+  deleteCompanyDocument: "delete_company_document_companies__company_id__documents__document_id__delete";
+  enrichCompany: "enrich_company_companies__company_id__enrich_post";
+  generateCompanyDocument: "generate_company_document_companies__company_id__documents_types__doc_type__generate_post";
+  getCompaniesOpenJobs: "get_companies_open_jobs_companies_open_jobs_post";
+  getCompany: "get_company_companies__company_id__get";
+  getCompanyBillingPrefill: "get_company_billing_prefill_companies__company_id__billing_prefill_get";
+  getCompanyContacts: "get_company_contacts_companies__company_id__contacts_get";
+  getCompanyDashboard: "get_company_dashboard_companies__company_id__dashboard_get";
+  getCompanyDetail: "get_company_detail_companies__company_id__detail_get";
+  getCompanyEngagementSummary: "get_company_engagement_summary_companies__company_id__engagement_summary_get";
+  getCompanyFormFields: "get_company_form_fields_companies_form_fields_get";
+  getCompanyIcpFit: "get_company_icp_fit_companies__company_id__icp_fit_get";
+  getCompanyIntelligenceData: "get_company_intelligence_data_companies__company_id__intelligence_data__data_type__get";
+  getCompanyIntelligenceStatus: "get_company_intelligence_status_companies__company_id__intelligence_status_get";
+  getCompanyIntelligenceSteps: "get_company_intelligence_steps_companies__company_id__intelligence_steps_get";
+  getCompanyNextBestStep: "get_company_next_best_step_companies__company_id__next_best_step_get";
+  getCompanyReviewStats: "get_company_review_stats_companies_review_stats_get";
+  getCompanySignals: "get_company_signals_companies__company_id__signals_get";
+  getCompanySitesVisited: "get_company_sites_visited_companies__company_id__sites_visited_get";
+  getCompanySynthesisReadiness: "get_company_synthesis_readiness_companies__company_id__synthesis_readiness_get";
+  getCompanyWorkflowStatus: "get_company_workflow_status_companies__company_id__workflow_status_get";
+  importCompanies: "import_companies_companies_import_post";
+  listCompanies: "list_companies_companies_get";
+  listCompaniesEnriched: "list_companies_enriched_companies_enriched_get";
+  listCompanyColumns: "list_company_columns_companies_columns_get";
+  listCompanyDocuments: "list_company_documents_companies__company_id__documents_get";
+  listCompanyPeople: "list_company_people_companies__company_id__people_get";
+  listCompanyTasks: "list_company_tasks_companies__company_id__tasks_get";
+  listContactsAcrossCompanies: "list_contacts_across_companies_companies_contacts_get";
+  mergeCompany: "merge_company_companies__company_id__merge_post";
+  mergeFilteredCompanies: "merge_filtered_companies_companies_merge_filtered_post";
+  previewCompanyMerge: "preview_company_merge_companies__company_id__merge_preview_get";
+  refreshCompanyBillingPrefill: "refresh_company_billing_prefill_companies__company_id__billing_prefill_refresh_post";
+  regenerateCompanyDocument: "regenerate_company_document_companies__company_id__documents_types__doc_type__regenerate_post";
+  removeCompanyContact: "remove_company_contact_companies__company_id__contacts__contact_id__delete";
+  retryCompanyIntelligence: "retry_company_intelligence_companies__company_id__retry_intelligence_post";
+  retryCompanySynthesis: "retry_company_synthesis_companies__company_id__retry_synthesis_post";
+  saveSkillResultToCompany: "save_skill_result_to_company_companies__company_id__documents_from_skill_post";
+  startCompanyWorkflow: "start_company_workflow_companies__company_id__workflows__workflow_type__start_post";
+  updateCompany: "update_company_companies__company_id__patch";
+}
+
+/** Input and output of every `g8.api.companies` operation, keyed by operationId. */
+export interface CompaniesOperations {
+  /**
+   * POST /companies/assign-owner
+   * Assign Company Owner
+   * tier: write · scope: companies:write
+   */
+  assign_company_owner_companies_assign_owner_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AssignOwnerMatchingRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies/{company_id}/contacts/{contact_id}
+   * Attach Company Contact
+   * tier: write · scope: companies:write
+   */
+  attach_company_contact_companies__company_id__contacts__contact_id__post: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+      /** Contact to link to the company. */
+      contact_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies/enrich/bulk
+   * Bulk Enrich Companies
+   * tier: billable · scope: enrichment:run
+   */
+  bulk_enrich_companies_companies_enrich_bulk_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies/enrich/people/bulk
+   * Bulk Enrich Company People
+   * tier: billable · scope: enrichment:run
+   */
+  bulk_enrich_company_people_companies_enrich_people_bulk_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies/enrich/stakeholders/bulk
+   * Bulk Enrich Company Stakeholders
+   * tier: billable · scope: enrichment:run
+   */
+  bulk_enrich_company_stakeholders_companies_enrich_stakeholders_bulk_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies
+   * Create Company
+   * tier: write · scope: companies:write
+   */
+  create_company_companies_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CompanyCreateRequest;
+  };
+    output: ApiResponse_CompanyCreateResponse_;
+  };
+  /**
+   * POST /companies/columns/create
+   * Create Company Column
+   * tier: write · scope: companies:write
+   */
+  create_company_column_companies_columns_create_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CreateCompanyColumnRequest;
+  };
+    output: ApiResponse_CreateCompanyColumnResponse_;
+  };
+  /**
+   * POST /companies/{company_id}/tasks
+   * Create Company Task
+   * tier: write · scope: companies:write
+   */
+  create_company_task_companies__company_id__tasks_post: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CompanyTaskCreateRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * DELETE /companies/{company_id}
+   * Delete Company
+   * tier: destructive · scope: companies:delete
+   */
+  delete_company_companies__company_id__delete: {
+    input: {
+    path: {
+      /** Company ID */
+      company_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * DELETE /companies/columns/{column_id}
+   * Delete Company Column
+   * tier: destructive · scope: companies:delete
+   */
+  delete_company_column_companies_columns__column_id__delete: {
+    input: {
+    path: {
+      /** ID of the column to delete */
+      column_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * DELETE /companies/{company_id}/documents/{document_id}
+   * Delete Company Document
+   * tier: destructive · scope: companies:delete
+   */
+  delete_company_document_companies__company_id__documents__document_id__delete: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+      /** Document id. */
+      document_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies/{company_id}/enrich
+   * Enrich Company
+   * tier: billable · scope: enrichment:run
+   */
+  enrich_company_companies__company_id__enrich_post: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies/{company_id}/documents/types/{doc_type}/generate
+   * Generate Company Document
+   * tier: billable · scope: enrichment:run
+   */
+  generate_company_document_companies__company_id__documents_types__doc_type__generate_post: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+      /** Document type, e.g. `account_brief`. */
+      doc_type: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies/open-jobs
+   * Get Companies Open Jobs
+   * tier: read · scope: companies:read
+   */
+  get_companies_open_jobs_companies_open_jobs_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CompaniesOpenJobsRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * GET /companies/{company_id}
+   * Get Company
+   * tier: read · scope: companies:read
+   */
+  get_company_companies__company_id__get: {
+    input: {
+    path: {
+      /** Company ID */
+      company_id: number;
+    };
+    query?: {
+      /** When true, the response includes a `custom_fields` object of custom column values keyed by column slug. Default false omits it. */
+      include_custom_fields?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CompanyResponse_;
+  };
+  /**
+   * GET /companies/{company_id}/billing-prefill
+   * Get Company Billing Prefill
+   * tier: read · scope: companies:read
+   */
+  get_company_billing_prefill_companies__company_id__billing_prefill_get: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/contacts
+   * Get Company Contacts
+   * tier: read · scope: companies:read
+   */
+  get_company_contacts_companies__company_id__contacts_get: {
+    input: {
+    path: {
+      /** Company ID */
+      company_id: number;
+    };
+    query?: {
+      /** Items per page (max 200) */
+      limit?: number;
+      /** Offset for pagination */
+      offset?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_CompanyContactItem__;
+  };
+  /**
+   * GET /companies/{company_id}/dashboard
+   * Get Company Dashboard
+   * tier: read · scope: companies:read
+   */
+  get_company_dashboard_companies__company_id__dashboard_get: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/detail
+   * Get Company Detail
+   * tier: read · scope: companies:read
+   */
+  get_company_detail_companies__company_id__detail_get: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+    };
+    query?: {
+      /** `auto` resolves the graph8 company id (integer or UUID); `company_id` resolves the global company business key. */
+      id_kind?: "auto" | "company_id";
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/engagement-summary
+   * Get Company Engagement Summary
+   * tier: read · scope: companies:read
+   */
+  get_company_engagement_summary_companies__company_id__engagement_summary_get: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies/form-fields
+   * Get Company Form Fields
+   * tier: read · scope: companies:read
+   */
+  get_company_form_fields_companies_form_fields_get: {
+    input: {
+    query?: {
+      /** Include this list's custom fields. */
+      list_id?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/icp-fit
+   * Get Company Icp Fit
+   * tier: read · scope: companies:read
+   */
+  get_company_icp_fit_companies__company_id__icp_fit_get: {
+    input: {
+    path: {
+      /** Company business key. */
+      company_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/intelligence-data/{data_type}
+   * Get Company Intelligence Data
+   * tier: read · scope: companies:read
+   */
+  get_company_intelligence_data_companies__company_id__intelligence_data__data_type__get: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+      /** Intelligence data type, e.g. `tech_stack`. */
+      data_type: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/intelligence-status
+   * Get Company Intelligence Status
+   * tier: read · scope: companies:read
+   */
+  get_company_intelligence_status_companies__company_id__intelligence_status_get: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/intelligence-steps
+   * Get Company Intelligence Steps
+   * tier: read · scope: companies:read
+   */
+  get_company_intelligence_steps_companies__company_id__intelligence_steps_get: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/next-best-step
+   * Get Company Next Best Step
+   * tier: billable · scope: enrichment:run
+   */
+  get_company_next_best_step_companies__company_id__next_best_step_get: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies/review-stats
+   * Get Company Review Stats
+   * tier: read · scope: companies:read
+   */
+  get_company_review_stats_companies_review_stats_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/signals
+   * Get Company Signals
+   * tier: read · scope: companies:read
+   */
+  get_company_signals_companies__company_id__signals_get: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/sites-visited
+   * Get Company Sites Visited
+   * tier: read · scope: companies:read
+   */
+  get_company_sites_visited_companies__company_id__sites_visited_get: {
+    input: {
+    path: {
+      /** Company business key. */
+      company_id: number;
+    };
+    query?: {
+      /** Lookback window. Bounded here rather than left open: the query is an unindexed analytics scan and an unbounded window is a cheap way to exhaust it. */
+      days?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/synthesis-readiness
+   * Get Company Synthesis Readiness
+   * tier: read · scope: companies:read
+   */
+  get_company_synthesis_readiness_companies__company_id__synthesis_readiness_get: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/workflow-status
+   * Get Company Workflow Status
+   * tier: read · scope: companies:read
+   */
+  get_company_workflow_status_companies__company_id__workflow_status_get: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+    };
+    query?: {
+      /** Also list the documents each workflow produced. */
+      include_documents?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies/import
+   * Import Companies
+   * tier: billable · scope: enrichment:run
+   */
+  import_companies_companies_import_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ImportCompaniesRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies
+   * List Companies
+   * tier: read · scope: companies:read
+   */
+  list_companies_companies_get: {
+    input: {
+    query?: {
+      /** Page number (1-indexed) */
+      page?: number;
+      /** Items per page (max 200) */
+      limit?: number;
+      /** Filter by domain (exact match) */
+      domain?: string | null;
+      /** Filter by industry (partial match) */
+      industry?: string | null;
+      /** Filter by company name (partial match) */
+      name?: string | null;
+      /** Minimum employee count */
+      employee_count_min?: number | null;
+      /** Maximum employee count */
+      employee_count_max?: number | null;
+      /** Filter by country (exact match) */
+      country?: string | null;
+      /** Filter by state (exact match) */
+      state?: string | null;
+      /** Filter by city (partial match) */
+      city?: string | null;
+      /** Filter by company description (partial match) */
+      description?: string | null;
+      /** Minimum annual revenue */
+      revenue_min?: number | null;
+      /** Maximum annual revenue */
+      revenue_max?: number | null;
+      /** Minimum founding year */
+      founded_year_min?: number | null;
+      /** Maximum founding year */
+      founded_year_max?: number | null;
+      /** Minimum LinkedIn followers */
+      linkedin_followers_min?: number | null;
+      /** Maximum LinkedIn followers */
+      linkedin_followers_max?: number | null;
+      /** When true, each company includes a `custom_fields` object of custom column values keyed by column slug. Default false keeps the legacy response shape and adds no extra query. */
+      include_custom_fields?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_CompanyListItem__;
+  };
+  /**
+   * GET /companies/enriched
+   * List Companies Enriched
+   * tier: read · scope: companies:read
+   */
+  list_companies_enriched_companies_enriched_get: {
+    input: {
+    query?: {
+      /** Rows to skip. */
+      skip?: number;
+      /** Rows to return. The app defaults this to 10000 - the entire roster in one response. Defaulted to 100 here; raise it deliberately. */
+      limit?: number;
+      /** Substring match on name or domain. */
+      search?: string | null;
+      /** Filter by record status, e.g. `prospect`. */
+      status?: string | null;
+      /** Filter by website status. */
+      website_status?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * GET /companies/columns
+   * List Company Columns
+   * tier: read · scope: companies:read
+   */
+  list_company_columns_companies_columns_get: {
+    input: {
+    query?: {
+      /** Optional list ID. When provided, list-specific dynamic columns are included alongside global ones. */
+      list_id?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_Column__;
+  };
+  /**
+   * GET /companies/{company_id}/documents
+   * List Company Documents
+   * tier: read · scope: companies:read
+   */
+  list_company_documents_companies__company_id__documents_get: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+    };
+    query?: {
+      /** Only documents in this folder. */
+      folder?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/people
+   * List Company People
+   * tier: read · scope: companies:read
+   */
+  list_company_people_companies__company_id__people_get: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/tasks
+   * List Company Tasks
+   * tier: read · scope: companies:read
+   */
+  list_company_tasks_companies__company_id__tasks_get: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: number;
+    };
+    query?: {
+      /** Only tasks in this status. */
+      task_status?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * GET /companies/contacts
+   * List Contacts Across Companies
+   * tier: read · scope: companies:read
+   */
+  list_contacts_across_companies_companies_contacts_get: {
+    input: {
+    query?: {
+      skip?: number;
+      /** The app defaults this to 10000; 100 here. */
+      limit?: number;
+      /** Substring match on name or email. */
+      search?: string | null;
+      /** Filter by job department. */
+      department?: string | null;
+      /** Filter by buying-committee role, e.g. `decision_maker`. */
+      buying_role?: string | null;
+      /** Only contacts attached to an open deal. */
+      in_pipeline?: boolean;
+      /** Filter by contact owner. */
+      owner_id?: string | null;
+      /** name | title | company_name | department | email | updated_at */
+      sort_by?: string;
+      /** asc | desc */
+      sort_order?: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * POST /companies/{company_id}/merge
+   * Merge Company
+   * tier: destructive · scope: companies:delete
+   */
+  merge_company_companies__company_id__merge_post: {
+    input: {
+    path: {
+      /** The company that SURVIVES the merge. */
+      company_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: MergeRecordRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies/merge-filtered
+   * Merge Filtered Companies
+   * tier: write · scope: companies:write
+   */
+  merge_filtered_companies_companies_merge_filtered_post: {
+    input: {
+    query?: {
+      /** Optional per-column filter JSON. */
+      filterModel?: string | null;
+      /** Optional sort JSON. */
+      sortModel?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: MergeFilteredRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /companies/{company_id}/merge/preview
+   * Preview Company Merge
+   * tier: read · scope: companies:read
+   */
+  preview_company_merge_companies__company_id__merge_preview_get: {
+    input: {
+    path: {
+      /** The company that SURVIVES the merge. */
+      company_id: number;
+    };
+    query: {
+      /** The company that would be merged AWAY. */
+      secondary: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies/{company_id}/billing-prefill/refresh
+   * Refresh Company Billing Prefill
+   * tier: write · scope: companies:write
+   */
+  refresh_company_billing_prefill_companies__company_id__billing_prefill_refresh_post: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies/{company_id}/documents/types/{doc_type}/regenerate
+   * Regenerate Company Document
+   * tier: billable · scope: enrichment:run
+   */
+  regenerate_company_document_companies__company_id__documents_types__doc_type__regenerate_post: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+      /** Document type. */
+      doc_type: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * DELETE /companies/{company_id}/contacts/{contact_id}
+   * Remove Company Contact
+   * tier: destructive · scope: companies:delete
+   */
+  remove_company_contact_companies__company_id__contacts__contact_id__delete: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+      /** Contact to unlink from the company. */
+      contact_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies/{company_id}/retry-intelligence
+   * Retry Company Intelligence
+   * tier: billable · scope: enrichment:run
+   */
+  retry_company_intelligence_companies__company_id__retry_intelligence_post: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body?: IntelligenceRetryRequest | null;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies/{company_id}/retry-synthesis
+   * Retry Company Synthesis
+   * tier: billable · scope: enrichment:run
+   */
+  retry_company_synthesis_companies__company_id__retry_synthesis_post: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies/{company_id}/documents/from-skill
+   * Save Skill Result To Company
+   * tier: write · scope: companies:write
+   */
+  save_skill_result_to_company_companies__company_id__documents_from_skill_post: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SaveSkillResultRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /companies/{company_id}/workflows/{workflow_type}/start
+   * Start Company Workflow
+   * tier: billable · scope: enrichment:run
+   */
+  start_company_workflow_companies__company_id__workflows__workflow_type__start_post: {
+    input: {
+    path: {
+      /** Company id. */
+      company_id: string;
+      /** Which workflow to run. */
+      workflow_type: CompanyWorkflowType;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * PATCH /companies/{company_id}
+   * Update Company
+   * tier: write · scope: companies:write
+   */
+  update_company_companies__company_id__patch: {
+    input: {
+    path: {
+      /** Company ID */
+      company_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CompanyUpdateRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+}
+
+// 43 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_CompanyCreateResponse_ {
+  data: CompanyCreateResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CompanyResponse_ {
+  data: CompanyResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CreateCompanyColumnResponse_ {
+  data: CreateCompanyColumnResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CrmCollectionPayload_ {
+  data: CrmCollectionPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CrmRecordPayload_ {
+  data: CrmRecordPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_dict_ {
+  data: Record<string, unknown>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_Column__ {
+  data: Array<Column>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_CompanyContactItem__ {
+  data: Array<CompanyContactItem>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_CompanyListItem__ {
+  data: Array<CompanyListItem>;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * Set the owner on every record matching a selection.
+ *
+ * A null `owner_id` UNASSIGNS the matching records rather than leaving them
+ * alone, so an omitted owner is a destructive instruction, not a no-op.
+ */
+export interface AssignOwnerMatchingRequest {
+  /** Per-column filters. */
+  filterModel?: Record<string, unknown>;
+  /** Restrict the selection to this list. */
+  list_id?: number | null;
+  /** Owner to assign. Null clears the owner on every match. */
+  owner_id?: string | null;
+  /** Advanced AND/OR filter tree. */
+  segmentFilter?: SegmentFilterGroup | null;
+}
+
+/**
+ * Column entity representing a database column definition.
+ * Used to describe table column metadata for MashupContact and other entities.
+ */
+export interface Column {
+  data_type?: ColumnType;
+  id?: number | null;
+  /** Automatically computed: True if object_id is None/empty, False otherwise. */
+  is_global: boolean;
+  name?: string | null;
+  object_id?: string | null;
+  source?: ColumnSource;
+  title: string;
+}
+
+/**
+ * Which entity a field in the contact field list belongs to.
+ *
+ * The ``GET /contacts/columns`` response deliberately combines fields from
+ * three provenances into one list (issue #21184): the person record, their
+ * employer's company record, and user-created custom columns. Consumers
+ * (form-mapping UI, AI-agent field listing, CSV import) need to tell them
+ * apart — a company field like ``COMPANY_REVENUE`` describes the employer,
+ * not the contact.
+ *
+ * - ``contact``: a field on the person record (``MashupContact.*``) — the default.
+ * - ``company``: a field on the contact's employer (``MashupCompany.*``),
+ *   surfaced so contacts can be mapped/filtered by company attributes.
+ * - ``custom``: a user-created dynamic column (global or list-scoped).
+ */
+export type ColumnSource = "contact" | "company" | "custom";
+
+/**
+ * User-selectable dynamic-column data types.
+ *
+ * Every member must have a physical type in the repos' pg_type_map
+ * (contacts/companies CDP repos + enrichment DynamicColumnRepository:
+ * int→INTEGER, numeric→NUMERIC, text→TEXT, boolean→BOOLEAN) and belong to
+ * the user-owned family in lists/usecases/dynamic_column_write_contract.py —
+ * both already list these four. Write paths coerce values per type via
+ * shared.infrustructure.db.cdp.dynamic_column_values.coerce_dynamic_value.
+ */
+export type ColumnType = "text" | "int" | "numeric" | "boolean";
+
+/**
+ * Request contract for the hiring-signal batch lookup.
+ *
+ * Field-for-field identical to the main-app model of the same name in
+ * ``companies/interfaces/fastapi/router.py``. It is redefined here rather
+ * than imported because that module imports
+ * ``developer_api.dependencies.hybrid_auth``; importing it back would couple
+ * the two app halves at import time. ``test_companies_open_jobs_api.py`` locks
+ * the two models together so the duplication cannot silently drift.
+ */
+export interface CompaniesOpenJobsRequest {
+  /** CRM company IDs (mashup_companies.id) - NOT linkedin_company_id */
+  company_ids: Array<number>;
+  /** False = counts only (one CH query) */
+  include_postings?: boolean;
+  /** Roll subsidiary postings into the parent. Off by default: one row = one company. NOTE: when true, `jobs` expands to child companies but `open_jobs` stays parent-only, so len(jobs) can exceed open_jobs. */
+  include_subsidiaries?: boolean;
+  limit_per_company?: number;
+  window_days?: number;
+}
+
+/**
+ * One contact in a company import.
+ *
+ * Contacts are grouped by email domain, so `email` decides which company a
+ * row lands on - `company_name` only names a company that does not exist yet.
+ */
+export interface CompanyContactImport {
+  /** Company name, used only when the domain is unknown. */
+  company_name?: string | null;
+  /** Company owner. */
+  company_owner?: string | null;
+  /** Contact owner. */
+  contact_owner?: string | null;
+  /** Email address. Also the company-grouping key. */
+  email: string;
+  /** First name. */
+  first_name: string;
+  /** Last name. */
+  last_name: string;
+  /** LinkedIn profile URL. */
+  linkedin_url?: string | null;
+  /** Phone number. */
+  phone?: string | null;
+  /** Buying-committee role: decision_maker | influencer | champion | end_user | blocker | coach. */
+  role?: string | null;
+  /** Job title. */
+  title?: string | null;
+}
+
+/** Contact summary within a company. */
+export interface CompanyContactItem {
+  city?: string | null;
+  country?: string | null;
+  direct_phone?: string | null;
+  first_name?: string | null;
+  full_name?: string | null;
+  id: number;
+  job_title?: string | null;
+  last_name?: string | null;
+  linkedin_url?: string | null;
+  seniority_level?: string | null;
+  state?: string | null;
+  work_email?: string | null;
+}
+
+/**
+ * Request body for creating a company.
+ *
+ * ``domain`` is required — it drives dedup (an existing company with the same
+ * domain is reused, not duplicated) and the Deals company picker. Every other
+ * field is optional.
+ */
+export interface CompanyCreateRequest {
+  address?: string | null;
+  city?: string | null;
+  country?: string | null;
+  /** Company domain, e.g. acme.com (required) */
+  domain: string;
+  employee_count?: string | null;
+  industry?: string | null;
+  linkedin_url?: string | null;
+  /** Optional list to add the company to after creation */
+  list_id?: number | null;
+  name?: string | null;
+  phone?: string | null;
+  state?: string | null;
+  website?: string | null;
+  zip?: string | null;
+}
+
+export interface CompanyCreateResponse {
+  company_id?: number | null;
+  merged?: boolean;
+  status: string;
+}
+
+/** Lighter company representation for list endpoints. */
+export interface CompanyListItem {
+  city?: string | null;
+  country?: string | null;
+  custom_fields?: (Record<string, string | null>) | null;
+  description?: string | null;
+  domain?: string | null;
+  employee_count?: string | null;
+  founded_year?: number | null;
+  id?: number | null;
+  industry?: string | null;
+  linkedin_followers?: string | null;
+  linkedin_url?: string | null;
+  logo_url?: string | null;
+  name?: string | null;
+  owner_id?: string | null;
+  owner_name?: string | null;
+  revenue?: string | null;
+  state?: string | null;
+  website?: string | null;
+}
+
+export interface CompanyResponse {
+  address?: string | null;
+  city?: string | null;
+  contact_count?: number | null;
+  country?: string | null;
+  created_at?: string | null;
+  crunchbase_url?: string | null;
+  custom_fields?: (Record<string, string | null>) | null;
+  description?: string | null;
+  domain?: string | null;
+  employee_count?: string | null;
+  facebook_url?: string | null;
+  founded_year?: number | null;
+  id: number;
+  industry?: string | null;
+  industry_group?: string | null;
+  linkedin_followers?: string | null;
+  linkedin_url?: string | null;
+  logo_url?: string | null;
+  meta_data?: Record<string, unknown> | null;
+  name?: string | null;
+  phone?: string | null;
+  revenue?: string | null;
+  state?: string | null;
+  twitter_url?: string | null;
+  updated_at?: string | null;
+  website?: string | null;
+  zip?: string | null;
+}
+
+/** Mirrors `companies.interfaces.fastapi.router.CompanyTaskCreateRequest`. */
+export interface CompanyTaskCreateRequest {
+  /** Assignee user id. */
+  assignee_id?: string | null;
+  /** Assignee display name. */
+  assignee_name?: string | null;
+  /** Task body. */
+  description?: string | null;
+  /** ISO-8601 due date. */
+  due_date?: string | null;
+  /** Priority, higher is more urgent. */
+  priority?: number | null;
+  /** Up to 20 labels. */
+  tags?: Array<string> | null;
+  /** Task type, e.g. `call`. */
+  task_type?: string | null;
+  /** Task title. */
+  title: string;
+}
+
+/** Request body for updating a company. All fields optional (partial update). */
+export interface CompanyUpdateRequest {
+  address?: string | null;
+  city?: string | null;
+  country?: string | null;
+  domain?: string | null;
+  employee_count?: string | null;
+  industry?: string | null;
+  linkedin_url?: string | null;
+  name?: string | null;
+  phone?: string | null;
+  state?: string | null;
+  website?: string | null;
+  zip?: string | null;
+}
+
+/** Types of workflows that can be run on a company */
+export type CompanyWorkflowType = "company_intelligence" | "stakeholder_mapping" | "deal_strategy" | "competitive_positioning";
+
+/**
+ * Request body for `POST /companies/columns/create`.
+ *
+ * Mirrors the shared `CreateColumnRequest` shape (`title`, `data_type`,
+ * `list_id`, `created_by`) plus an OPTIONAL `enrichment` block that, when
+ * supplied, provisions a companion waterfall pipeline in the same
+ * request — so the new column is immediately runnable via
+ * `POST /enrichment/waterfall/enrich`.
+ *
+ * Without the `enrichment` block the column is created, but it has no
+ * enrichment plan; the UI "Enrich" button (and `g8_enrich_contacts` in
+ * waterfall mode) will return 422 (`waterfall_config_missing`) until a
+ * pipeline is provisioned separately via
+ * `POST /enrichment/waterfall/configs`.
+ *
+ * Backwards compatible: callers that previously POSTed only `title` /
+ * `data_type` / `list_id` / `created_by` continue to work unchanged.
+ */
+export interface CreateCompanyColumnRequest {
+  /** Email of the user creating the column (for audit). */
+  created_by: string;
+  /** Column data type. Currently only 'text' is supported. */
+  data_type?: ColumnType;
+  /** STRONGLY RECOMMENDED. Optional waterfall enrichment block. When supplied, a companion `enrichment_configs` row is created alongside the column so the UI 'Enrich' button works immediately. Without it the column exists but isn't enrichable until a pipeline is configured via POST /enrichment/waterfall/configs. */
+  enrichment?: CreateFieldEnrichmentInput | null;
+  /** If set, the column is list-scoped (only visible on that list). Required when `enrichment` is supplied — waterfall pipelines are list-scoped. */
+  list_id?: number | null;
+  /** Column title shown in the UI (e.g. 'Tier') */
+  title: string;
+}
+
+/**
+ * Response shape for `POST /companies/columns/create`.
+ *
+ * Mirrors the `Column` entity fields verbatim so existing callers reading
+ * `data.id` / `data.title` / `data.name` / `data.is_global` etc. keep
+ * working without code changes. Adds one new optional `enrichment` field
+ * that is populated when the request included an `enrichment` block.
+ */
+export interface CreateCompanyColumnResponse {
+  data_type?: ColumnType;
+  /** Populated when the request included an `enrichment` block. Use `enrichment.column_id` for subsequent POST /enrichment/waterfall/enrich calls. */
+  enrichment?: CreateFieldEnrichmentResponse | null;
+  id?: number | null;
+  /** Computed: True when object_id is null/empty (global column). */
+  is_global?: boolean;
+  name?: string | null;
+  object_id?: string | null;
+  title: string;
+}
+
+/**
+ * Optional enrichment-pipeline block attached at column-create time.
+ *
+ * When supplied, `POST /fields` creates a companion `enrichment_configs`
+ * row in the same request so the new column is immediately runnable via
+ * `POST /enrichment/waterfall/enrich`. Without this block the column
+ * exists but has no enrichment plan — calling /waterfall/enrich on it
+ * returns 422 (`waterfall_config_missing`).
+ *
+ * Currently only `type='waterfall'` is supported; AI / formula
+ * enrichment will follow once the rest of the agent surface lands.
+ */
+export interface CreateFieldEnrichmentInput {
+  /** Optional post-enrichment email verification config. */
+  email_verification?: EmailVerificationInput | null;
+  /** Target field identifier. Defaults to the new column's slug. */
+  field_to_enrich?: string | null;
+  /** Pipeline name. Defaults to `<column title> Enrichment` if omitted. */
+  name?: string | null;
+  /** Ordered list of provider names. Without `target_field`, server maps each to its default email-finder action (legacy). With `target_field`, filters the column template to these providers (correct per-field action preserved). Mutually exclusive with `steps`. */
+  providers?: Array<string> | null;
+  /** If true, skip rows where the target field is already populated. */
+  skip_existing_values?: boolean;
+  /** Full caller-supplied step list. Persisted verbatim. Mutually exclusive with `providers`. */
+  steps?: Array<WaterfallStepInput> | null;
+  /** Kind of data this column holds — CONTACT_DIRECT_PHONE, CONTACT_MOBILE_PHONE, CONTACT_WORK_EMAIL, CONTACT_LINKEDIN_URL, COMPANY_PHONE, ... or a friendly synonym ('phone', 'mobile', 'email', 'linkedin'). When set, the pipeline is built from the server's per-column TEMPLATE so each provider runs its CORRECT action for that data kind (e.g. leadmagic `mobile_finder` for a phone, NOT `email_finder`) — the same actions the web UI's 'Add column -> Waterfall' picks. Combine with `providers[]` to keep only those providers from the template. Mutually exclusive with `steps`. When omitted, the legacy `providers[]` email-finder shortcut is unchanged. */
+  target_field?: string | null;
+  /** Pipeline kind. Only 'waterfall' is supported today. */
+  type?: string;
+}
+
+/** Echo of the companion enrichment config created by `enrichment` block. */
+export interface CreateFieldEnrichmentResponse {
+  /** column_id slug to pass to /enrichment/waterfall/enrich */
+  column_id: string;
+  config_id: string;
+  email_verification?: Record<string, unknown> | null;
+  name: string;
+  providers?: Array<string>;
+  type: string;
+}
+
+/** An open envelope for a LIST result, so a bare list keeps its shape. */
+export interface CrmCollectionPayload {
+  items?: Array<unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * An open envelope for one record, one dashboard or one job receipt.
+ *
+ * Open because most of these reads are COMPUTED shapes - an engagement
+ * summary, a next-best-step, an intelligence status - that grow with the
+ * product, and dropping a field from an advisory read makes it say "nothing
+ * to report" rather than "we did not tell you".
+ */
+export type CrmRecordPayload = Record<string, unknown>;
+
+/**
+ * Email verification config attached to a waterfall pipeline.
+ *
+ * Mirrors the canonical `EmailVerificationConfigDto` in
+ * `enrichment/interfaces/fastapi/waterfall_dtos.py` so the dev-API and the
+ * UI persist an identical settings shape (the CF worker reads `settings.
+ * email_verification.*` regardless of which surface saved the pipeline).
+ */
+export interface EmailVerificationInput {
+  /** Treat catch-all responses as valid (domains that accept any address). */
+  accept_catchall?: boolean;
+  /** Enable post-enrichment email verification */
+  enabled?: boolean;
+  /** Verification provider. Charges credits when use_system_credentials=True. */
+  provider?: "zerobounce" | "hunter" | "icypeas" | "leadmagic";
+  /** Use graph8-managed API keys (charges credits). False = use org's BYOK keys. */
+  use_system_credentials?: boolean;
+  /** Verification statuses to accept as valid. Typical: ['valid'] or ['valid','catch-all']. */
+  valid_statuses?: Array<string>;
+}
+
+/**
+ * One structured filter condition.
+ *
+ * Mirrors `shared.interfaces.fastapi.dtos.DtoCondition`.
+ */
+export interface FilterCondition {
+  /** Field name to apply the condition to. */
+  field: string;
+  /** Operator, e.g. `=`, `in`, `like`. */
+  operator?: string;
+  /** Value to compare against. */
+  value?: unknown;
+  /** Secondary value, for range operators. */
+  value_to?: unknown | null;
+}
+
+/**
+ * Create or update companies from a batch of contacts.
+ *
+ * Grouping is by email domain: a new domain creates a company, a known one
+ * is updated in place. There is no separate "company" payload.
+ */
+export interface ImportCompaniesRequest {
+  /** Contacts to import. */
+  contacts: Array<CompanyContactImport>;
+  /** Where the records came from, recorded on the import. */
+  source: string;
+}
+
+/**
+ * Re-run company intelligence generation. SPENDS CREDITS.
+ *
+ * Omitting `doc_types` regenerates the DEFAULT set rather than nothing, so
+ * an empty body is the expensive option, not the cheap one.
+ */
+export interface IntelligenceRetryRequest {
+  /** Document types to generate. Omit for the default set. */
+  doc_types?: Array<string> | null;
+}
+
+/** Which side of a merge wins one field. */
+export interface MergeFieldOverride {
+  /** Field name, e.g. `CONTACT_JOB_TITLE`. */
+  field: string;
+  /** Which record's value to keep. */
+  winner: "primary" | "secondary";
+}
+
+/**
+ * Add every record matching a filter into a target list.
+ *
+ * Mirrors `MergeFilteredContactsRequest` / `MergeFilteredCompaniesRequest`,
+ * which are field-identical. Despite the name this MERGES A SELECTION INTO A
+ * LIST - it does not merge duplicate records together. `/duplicates` is the
+ * surface that does that.
+ *
+ * On a 409 the call is telling you some records need a decision; re-send
+ * with `conflict_resolution` set.
+ */
+export interface MergeFilteredRequest {
+  /** Required when retrying after a 409. `add_all` takes every warned record, `skip_all` takes none of them, `custom` takes the ids in `include_warned_ids`. Blocked records are excluded either way. */
+  conflict_resolution?: ("add_all" | "skip_all" | "custom") | null;
+  /** Source-column to target-column mapping for custom columns. */
+  dynamic_column_mapping?: Record<string, string>;
+  /** Conditions selecting the source records. */
+  filter?: Array<FilterCondition>;
+  /** With `conflict_resolution=custom`, the warned ids to include. */
+  include_warned_ids?: Array<string> | null;
+  /** Advanced AND/OR filter tree. */
+  segmentFilter?: SegmentFilterGroup | null;
+  /** List the matching records are added to. */
+  target_list_id: number;
+}
+
+/**
+ * Merge `secondary_id` INTO the record in the path. The secondary stops existing.
+ *
+ * Mirrors `_MergeContactRequest` / `_MergeCompanyRequest`, which are identical.
+ */
+export interface MergeRecordRequest {
+  /** The bulk criterion, when `trigger` is `bulk_criterion`. */
+  bulk_criterion?: string | null;
+  /** Decide individual fields instead of the app's rules. */
+  field_overrides?: Array<MergeFieldOverride>;
+  /** The record merged AWAY. */
+  secondary_id: number;
+  /** The duplicate suggestion this merge acts on, if any. */
+  suggestion_id?: string | null;
+  /** What prompted the merge. Recorded on the audit row. */
+  trigger?: "manual" | "bulk_criterion";
+}
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}
+
+/** Attach the output of a skill run to a record as a document. */
+export interface SaveSkillResultRequest {
+  /** Action within that execution. */
+  action_name: string;
+  /** Document body to store. */
+  content: string;
+  /** The skill execution that produced the content. */
+  execution_id: string;
+}
+
+/**
+ * An AND/OR group of leaves and nested groups, at most three groups deep.
+ *
+ * Mirrors `SegmentFilterGroup` in `contacts.domain.value_objects.ag_grid_models`.
+ * `op` is closed because the app REFUSES an unrecognised connector rather
+ * than defaulting to AND - defaulting would silently return a different
+ * result set, and on a destructive route that is a different set of records
+ * acted on.
+ *
+ * FIXED DEPTH, NOT RECURSIVE. The app's model is self-referencing; the
+ * published one deliberately is not, because a schema that reaches itself
+ * through `$ref` sends the docs renderer into unbounded recursion. Three
+ * group levels (this one, `SegmentFilterSubgroup`, `SegmentFilterInnerGroup`)
+ * cover every filter the app's own builder produces; the app's larger depth
+ * and leaf budget still applies and surfaces as a 422.
+ */
+export interface SegmentFilterGroup {
+  /** Nested groups and/or leaf conditions. */
+  children?: Array<SegmentFilterSubgroup | SegmentFilterLeaf>;
+  /** Connector for this group. Case-insensitive. */
+  op: "AND" | "OR" | "and" | "or";
+}
+
+/** The third and deepest group level: leaf conditions only. */
+export interface SegmentFilterInnerGroup {
+  /** Leaf conditions. */
+  children?: Array<SegmentFilterLeaf>;
+  /** Connector for this group. Case-insensitive. */
+  op: "AND" | "OR" | "and" | "or";
+}
+
+/**
+ * One field-level condition inside an advanced-filter tree.
+ *
+ * Mirrors `contacts.domain.value_objects.ag_grid_models.SegmentFilterLeaf`.
+ * `op` is CLOSED here: the app compiles its UI vocabulary down to this
+ * canonical set before sending, and an unrecognised operator reaching the
+ * SQL builder is a 500 rather than a refusal naming the valid operators.
+ */
+export interface SegmentFilterLeaf {
+  /** Column to test, e.g. `CONTACT_JOB_TITLE`. */
+  field: string;
+  /** Comparison to apply. */
+  op: "eq" | "neq" | "lt" | "lte" | "gt" | "gte" | "contains" | "icontains" | "starts_with" | "ends_with" | "in" | "not_in" | "between" | "is_null" | "is_not_null";
+  /** Value to compare against. */
+  value?: unknown | null;
+  /** Upper bound. Only meaningful with `between`. */
+  valueTo?: unknown | null;
+}
+
+/** The second group level: leaves and/or innermost groups. */
+export interface SegmentFilterSubgroup {
+  /** Innermost groups and/or leaf conditions. */
+  children?: Array<SegmentFilterInnerGroup | SegmentFilterLeaf>;
+  /** Connector for this group. Case-insensitive. */
+  op: "AND" | "OR" | "and" | "or";
+}
+
+/**
+ * Single step in a caller-supplied waterfall sequence.
+ *
+ * Mirrors `WaterfallStepDto` in `enrichment/interfaces/fastapi/waterfall_dtos.py`.
+ * Persisted verbatim into `enrichment_configs.config.steps[]` so the CF
+ * worker can resolve provider, action and credentials the same way
+ * UI-saved pipelines do.
+ */
+export interface WaterfallStepInput {
+  /** Provider action: lookup_person, find_email, enrich_person, ... */
+  action: string;
+  /** Human-readable label shown in UI. Auto-titled from `action` if omitted. */
+  action_display_name?: string | null;
+  confidence_threshold?: number;
+  /** Provider-specific options (e.g. apollo `reveal_phone_numbers=true`). */
+  config?: Record<string, unknown>;
+  enabled?: boolean;
+  /** Step identifier. Auto-generated (`step_<provider>_<uuid8>`) if omitted. */
+  id?: string | null;
+  /** Maps provider input names to graph8 column identifiers (CONTACT_*). */
+  input_mapping?: Record<string, string>;
+  /** True = use graph8-managed credentials + charge credits. False = use org BYOK. */
+  is_system_provider?: boolean;
+  max_retries?: number;
+  /** 0-indexed execution order. */
+  order?: number;
+  /** Dotted path the worker writes into (e.g. 'contact.work_email'). */
+  output_field?: string | null;
+  /** Optional output field remap (deprecated — prefer `output_field`). */
+  output_mapping?: Record<string, string>;
+  /** Provider name: graph8, hunter, prospeo, dropcontact, apollo, ... */
+  provider: string;
+  stop_on_success?: boolean;
+}