@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/contacts.d.ts

@@ -0,0 +1,2173 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.contacts` (Contacts): 70 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"assign_contact_owner_contacts_assign_owner_post">;
+ *
+ * Reference with examples: contacts.md
+ */
+/* eslint-disable */
+
+/** `g8.api.contacts.<member>` -> the operationId it calls. */
+export interface ContactsMembers {
+  assignContactOwner: "assign_contact_owner_contacts_assign_owner_post";
+  assignContactTags: "assign_contact_tags_contacts_tags_assign_post";
+  batchContactRelated: "batch_contact_related_contacts_related_post";
+  bulkGetContacts: "bulk_get_contacts_contacts_bulk_get_post";
+  bulkUpdateContacts: "bulk_update_contacts_contacts_bulk_update_post";
+  cancelRecordWorkflowExecution: "cancel_record_workflow_execution_contacts_workflow_executions__execution_id__cancel_post";
+  createContactColumn: "create_contact_column_contacts_columns_create_post";
+  createContactTag: "create_contact_tag_contacts_tags_post";
+  createContacts: "create_contacts_contacts_post";
+  decideRecordWorkflowExecution: "decide_record_workflow_execution_contacts_workflow_executions__execution_id__approve_post";
+  deleteContact: "delete_contact_contacts__contact_id__delete";
+  deleteContactColumn: "delete_contact_column_contacts_columns__column_id__delete";
+  deleteContactDocument: "delete_contact_document_contacts__contact_id__documents__document_id__delete";
+  deleteContactTag: "delete_contact_tag_contacts_tags__tag_id__delete";
+  fetchContacts: "fetch_contacts_contacts_fetch_post";
+  generateAllContactDocuments: "generate_all_contact_documents_contacts__contact_id__documents_generate_all_post";
+  generateContactDocument: "generate_contact_document_contacts__contact_id__documents_types__doc_type__generate_post";
+  getActivityFeed: "get_activity_feed_activity_feed_get";
+  getContact: "get_contact_contacts__contact_id__get";
+  getContactAnalysis: "get_contact_analysis_contacts__contact_id__analysis_get";
+  getContactDashboard: "get_contact_dashboard_contacts__contact_id__dashboard_get";
+  getContactDashboardStats: "get_contact_dashboard_stats_contacts_dashboard_stats_get";
+  getContactDetail: "get_contact_detail_contacts__contact_id__detail_get";
+  getContactDocument: "get_contact_document_contacts__contact_id__documents_types__doc_type__get";
+  getContactEngagementSummary: "get_contact_engagement_summary_contacts__contact_id__engagement_summary_get";
+  getContactFormFields: "get_contact_form_fields_contacts_form_fields_get";
+  getContactGenerationStatus: "get_contact_generation_status_contacts__contact_id__documents_generation_status_get";
+  getContactLists: "get_contact_lists_contacts__contact_id__lists_get";
+  getContactMeetings: "get_contact_meetings_contacts__contact_id__meetings_get";
+  getContactNextBestStep: "get_contact_next_best_step_contacts__contact_id__next_best_step_get";
+  getContactProfilePictures: "get_contact_profile_pictures_contacts_profile_pictures_post";
+  getContactRowDetail: "get_contact_row_detail_contacts_row_detail__record_id__get";
+  getContactSequences: "get_contact_sequences_contacts__contact_id__sequences_get";
+  getContactSignals: "get_contact_signals_contacts__contact_id__signals_get";
+  getContactSitesVisited: "get_contact_sites_visited_contacts__contact_id__sites_visited_get";
+  getContactTagIds: "get_contact_tag_ids_contacts__contact_id__tags_get";
+  getDuplicateSettings: "get_duplicate_settings_duplicates_settings_get";
+  getRecordColumnValues: "get_record_column_values_contacts_column_values_post";
+  listBaseColumns: "list_base_columns_contacts_base_columns_get";
+  listColumnNames: "list_column_names_contacts_column_names_get";
+  listContactColumnDefinitions: "list_contact_column_definitions_contacts_column_definitions_get";
+  listContactColumns: "list_contact_columns_contacts_columns_get";
+  listContactDocuments: "list_contact_documents_contacts__contact_id__documents_get";
+  listContactTags: "list_contact_tags_contacts_tags_get";
+  listContacts: "list_contacts_contacts_get";
+  listCustomColumnDefinitions: "list_custom_column_definitions_contacts_custom_column_definitions_get";
+  listDuplicateDetectionRuns: "list_duplicate_detection_runs_duplicates_detection_runs_get";
+  listRecordWorkflowExecutions: "list_record_workflow_executions_contacts_workflow_executions_get";
+  listSearchableFields: "list_searchable_fields_contacts_searchable_fields_get";
+  mergeContact: "merge_contact_contacts__contact_id__merge_post";
+  mergeContactTags: "merge_contact_tags_contacts_tags_merge_post";
+  mergeFilteredContacts: "merge_filtered_contacts_contacts_merge_filtered_post";
+  pauseRecordWorkflowExecution: "pause_record_workflow_execution_contacts_workflow_executions__execution_id__pause_post";
+  previewContactMerge: "preview_contact_merge_contacts__contact_id__merge_preview_get";
+  previewDetectionRule: "preview_detection_rule_duplicates_settings_preview_detection_rule_post";
+  regenerateContactDocument: "regenerate_contact_document_contacts__contact_id__documents_types__doc_type__regenerate_post";
+  resumeRecordWorkflowExecution: "resume_record_workflow_execution_contacts_workflow_executions__execution_id__resume_post";
+  runDuplicateDetection: "run_duplicate_detection_duplicates_detection_run_post";
+  runRecordWorkflow: "run_record_workflow_contacts_workflow_executions_run_post";
+  saveSkillResultToContact: "save_skill_result_to_contact_contacts__contact_id__documents_from_skill_post";
+  triggerAutoMerge: "trigger_auto_merge_duplicates_auto_merge_post";
+  unassignContactTags: "unassign_contact_tags_contacts_tags_unassign_post";
+  unlockContactInfo: "unlock_contact_info_contacts_unlock_info_post";
+  updateContact: "update_contact_contacts__contact_id__patch";
+  updateContactDocument: "update_contact_document_contacts__contact_id__documents__document_id__put";
+  updateContactTag: "update_contact_tag_contacts_tags__tag_id__patch";
+  updateDuplicateSettings: "update_duplicate_settings_duplicates_settings_put";
+  verifyContactEmails: "verify_contact_emails_contacts_verify_email_post";
+  verifyContactEmailsAsync: "verify_contact_emails_async_contacts_verify_email_async_post";
+  withdrawContactsFromSequences: "withdraw_contacts_from_sequences_contacts_withdraw_from_sequences_post";
+}
+
+/** Input and output of every `g8.api.contacts` operation, keyed by operationId. */
+export interface ContactsOperations {
+  /**
+   * POST /contacts/assign-owner
+   * Assign Contact Owner
+   * tier: write · scope: contacts:write
+   */
+  assign_contact_owner_contacts_assign_owner_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AssignOwnerMatchingRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /contacts/tags/assign
+   * Assign Contact Tags
+   * tier: write · scope: contacts:write
+   */
+  assign_contact_tags_contacts_tags_assign_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ContactTagAssignRequest;
+  };
+    output: ApiResponse_ContactTagWriteResult_;
+  };
+  /**
+   * POST /contacts/related
+   * Batch Contact Related
+   * tier: read · scope: contacts:read
+   */
+  batch_contact_related_contacts_related_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ContactRelatedBatchRequest;
+  };
+    output: ApiResponse_ContactRelatedBatchResponse_;
+  };
+  /**
+   * POST /contacts/bulk-get
+   * Bulk Get Contacts
+   * tier: read · scope: contacts:read
+   */
+  bulk_get_contacts_contacts_bulk_get_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ContactBulkGetRequest;
+  };
+    output: ApiResponse_ContactBulkGetResponse_;
+  };
+  /**
+   * POST /contacts/bulk-update
+   * Bulk Update Contacts
+   * tier: write · scope: contacts:write
+   */
+  bulk_update_contacts_contacts_bulk_update_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: Array<Record<string, unknown>>;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /contacts/workflow-executions/{execution_id}/cancel
+   * Cancel Record Workflow Execution
+   * tier: destructive · scope: contacts:delete
+   */
+  cancel_record_workflow_execution_contacts_workflow_executions__execution_id__cancel_post: {
+    input: {
+    path: {
+      /** Workflow execution id. */
+      execution_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /contacts/columns/create
+   * Create Contact Column
+   * tier: write · scope: contacts:write
+   */
+  create_contact_column_contacts_columns_create_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CreateContactColumnRequest;
+  };
+    output: ApiResponse_CreateContactColumnResponse_;
+  };
+  /**
+   * POST /contacts/tags
+   * Create Contact Tag
+   * tier: write · scope: contacts:write
+   */
+  create_contact_tag_contacts_tags_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ContactTagCreateRequest;
+  };
+    output: ApiResponse_ContactTag_;
+  };
+  /**
+   * POST /contacts
+   * Create Contacts
+   * tier: write · scope: contacts:write
+   */
+  create_contacts_contacts_post: {
+    input: {
+    headers?: {
+      /** Optional. Retrying a create with the same key returns the first response instead of creating a duplicate (cached 24h). Omit for the existing non-idempotent behavior. */
+      "Idempotency-Key"?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ContactCreateRequest;
+  };
+    output: ApiResponse_ContactCreateResponse_;
+  };
+  /**
+   * POST /contacts/workflow-executions/{execution_id}/approve
+   * Decide Record Workflow Execution
+   * tier: write · scope: contacts:write
+   */
+  decide_record_workflow_execution_contacts_workflow_executions__execution_id__approve_post: {
+    input: {
+    path: {
+      /** Workflow execution id. */
+      execution_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ApproveExecutionRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * DELETE /contacts/{contact_id}
+   * Delete Contact
+   * tier: destructive · scope: contacts:delete
+   */
+  delete_contact_contacts__contact_id__delete: {
+    input: {
+    path: {
+      /** Contact ID */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * DELETE /contacts/columns/{column_id}
+   * Delete Contact Column
+   * tier: destructive · scope: contacts:delete
+   */
+  delete_contact_column_contacts_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 /contacts/{contact_id}/documents/{document_id}
+   * Delete Contact Document
+   * tier: destructive · scope: contacts:delete
+   */
+  delete_contact_document_contacts__contact_id__documents__document_id__delete: {
+    input: {
+    path: {
+      /** Contact id. */
+      contact_id: number;
+      /** Document id. */
+      document_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * DELETE /contacts/tags/{tag_id}
+   * Delete Contact Tag
+   * tier: destructive · scope: contacts:delete
+   */
+  delete_contact_tag_contacts_tags__tag_id__delete: {
+    input: {
+    path: {
+      /** Tag id. */
+      tag_id: string;
+    };
+    query?: {
+      /** Move every assignment to this tag before deleting. Omit to drop the assignments with the tag. */
+      reassign_to?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ContactTagWriteResult_;
+  };
+  /**
+   * POST /contacts/fetch
+   * Fetch Contacts
+   * tier: read · scope: contacts:read
+   */
+  fetch_contacts_contacts_fetch_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FetchContactsRequest;
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * POST /contacts/{contact_id}/documents/generate-all
+   * Generate All Contact Documents
+   * tier: billable · scope: enrichment:run
+   */
+  generate_all_contact_documents_contacts__contact_id__documents_generate_all_post: {
+    input: {
+    path: {
+      /** Contact primary key. */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /contacts/{contact_id}/documents/types/{doc_type}/generate
+   * Generate Contact Document
+   * tier: billable · scope: enrichment:run
+   */
+  generate_contact_document_contacts__contact_id__documents_types__doc_type__generate_post: {
+    input: {
+    path: {
+      /** Contact id. */
+      contact_id: number;
+      /** Document type. */
+      doc_type: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /activity-feed
+   * Get Activity Feed
+   * tier: read · scope: contacts:read
+   */
+  get_activity_feed_activity_feed_get: {
+    input: {
+    query: {
+      /** contact | company | deal | team_member */
+      entity_type: string;
+      /** Id of that record. */
+      entity_id: string;
+      /** Comma-separated subset of task,note,email,call,meeting,sms,chat,stage_change,quote,record_change,deal. Omit for all. */
+      types?: string | null;
+      /** manual | crm | system | dialer | automation | api | all */
+      source?: string;
+      /** ISO 8601 cursor; returns events at or after it. */
+      since?: string | null;
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * GET /contacts/{contact_id}
+   * Get Contact
+   * tier: read · scope: contacts:read
+   */
+  get_contact_contacts__contact_id__get: {
+    input: {
+    path: {
+      /** Contact ID */
+      contact_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_ContactResponse_;
+  };
+  /**
+   * GET /contacts/{contact_id}/analysis
+   * Get Contact Analysis
+   * tier: read · scope: contacts:read
+   */
+  get_contact_analysis_contacts__contact_id__analysis_get: {
+    input: {
+    path: {
+      /** Contact id. */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /contacts/{contact_id}/dashboard
+   * Get Contact Dashboard
+   * tier: read · scope: contacts:read
+   */
+  get_contact_dashboard_contacts__contact_id__dashboard_get: {
+    input: {
+    path: {
+      /** Contact primary key. */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /contacts/dashboard-stats
+   * Get Contact Dashboard Stats
+   * tier: read · scope: contacts:read
+   */
+  get_contact_dashboard_stats_contacts_dashboard_stats_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /contacts/{contact_id}/detail
+   * Get Contact Detail
+   * tier: read · scope: contacts:read
+   */
+  get_contact_detail_contacts__contact_id__detail_get: {
+    input: {
+    path: {
+      /** Contact id. */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /contacts/{contact_id}/documents/types/{doc_type}
+   * Get Contact Document
+   * tier: read · scope: contacts:read
+   */
+  get_contact_document_contacts__contact_id__documents_types__doc_type__get: {
+    input: {
+    path: {
+      /** Contact id. */
+      contact_id: number;
+      /** Document type, e.g. `contact_brief`. */
+      doc_type: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /contacts/{contact_id}/engagement-summary
+   * Get Contact Engagement Summary
+   * tier: read · scope: contacts:read
+   */
+  get_contact_engagement_summary_contacts__contact_id__engagement_summary_get: {
+    input: {
+    path: {
+      /** Contact primary key. */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /contacts/form-fields
+   * Get Contact Form Fields
+   * tier: read · scope: contacts:read
+   */
+  get_contact_form_fields_contacts_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 /contacts/{contact_id}/documents/generation-status
+   * Get Contact Generation Status
+   * tier: read · scope: contacts:read
+   */
+  get_contact_generation_status_contacts__contact_id__documents_generation_status_get: {
+    input: {
+    path: {
+      /** Contact primary key. */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /contacts/{contact_id}/lists
+   * Get Contact Lists
+   * tier: read · scope: contacts:read
+   */
+  get_contact_lists_contacts__contact_id__lists_get: {
+    input: {
+    path: {
+      /** Contact primary key (`mashup_contacts.id`). */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * GET /contacts/{contact_id}/meetings
+   * Get Contact Meetings
+   * tier: read · scope: contacts:read
+   */
+  get_contact_meetings_contacts__contact_id__meetings_get: {
+    input: {
+    path: {
+      /** Contact id. */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * GET /contacts/{contact_id}/next-best-step
+   * Get Contact Next Best Step
+   * tier: billable · scope: enrichment:run
+   */
+  get_contact_next_best_step_contacts__contact_id__next_best_step_get: {
+    input: {
+    path: {
+      /** Contact primary key. */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /contacts/profile-pictures
+   * Get Contact Profile Pictures
+   * tier: read · scope: contacts:read
+   */
+  get_contact_profile_pictures_contacts_profile_pictures_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ProfilePicturesRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /contacts/row-detail/{record_id}
+   * Get Contact Row Detail
+   * tier: read · scope: contacts:read
+   */
+  get_contact_row_detail_contacts_row_detail__record_id__get: {
+    input: {
+    path: {
+      /** Record primary key. */
+      record_id: number;
+    };
+    query: {
+      /** Required: the list the record is read through. */
+      list_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /contacts/{contact_id}/sequences
+   * Get Contact Sequences
+   * tier: read · scope: contacts:read
+   */
+  get_contact_sequences_contacts__contact_id__sequences_get: {
+    input: {
+    path: {
+      /** Contact id. */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * GET /contacts/{contact_id}/signals
+   * Get Contact Signals
+   * tier: read · scope: contacts:read
+   */
+  get_contact_signals_contacts__contact_id__signals_get: {
+    input: {
+    path: {
+      /** Contact id. */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /contacts/{contact_id}/sites-visited
+   * Get Contact Sites Visited
+   * tier: read · scope: contacts:read
+   */
+  get_contact_sites_visited_contacts__contact_id__sites_visited_get: {
+    input: {
+    path: {
+      /** Contact primary key. */
+      contact_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 /contacts/{contact_id}/tags
+   * Get Contact Tag Ids
+   * tier: read · scope: contacts:read
+   */
+  get_contact_tag_ids_contacts__contact_id__tags_get: {
+    input: {
+    path: {
+      /** Contact id. */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /duplicates/settings
+   * Get Duplicate Settings
+   * tier: read · scope: contacts:read
+   */
+  get_duplicate_settings_duplicates_settings_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /contacts/column-values
+   * Get Record Column Values
+   * tier: read · scope: contacts:read
+   */
+  get_record_column_values_contacts_column_values_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RecordColumnValuesRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /contacts/base-columns
+   * List Base Columns
+   * tier: read · scope: contacts:read
+   */
+  list_base_columns_contacts_base_columns_get: {
+    input: {
+    query: {
+      /** Required: the list decides which base columns exist. */
+      list_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * GET /contacts/column-names
+   * List Column Names
+   * tier: read · scope: contacts:read
+   */
+  list_column_names_contacts_column_names_get: {
+    input: {
+    query?: {
+      /** Include this list's own columns. */
+      list_id?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * GET /contacts/column-definitions
+   * List Contact Column Definitions
+   * tier: read · scope: contacts:read
+   */
+  list_contact_column_definitions_contacts_column_definitions_get: {
+    input: {
+    query?: {
+      /** Include the columns specific to this list. The list also decides whether contact or company columns are returned - a companies list returns company columns from this contacts path. */
+      list_id?: number | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * GET /contacts/columns
+   * List Contact Columns
+   * tier: read · scope: contacts:read
+   */
+  list_contact_columns_contacts_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 /contacts/{contact_id}/documents
+   * List Contact Documents
+   * tier: read · scope: contacts:read
+   */
+  list_contact_documents_contacts__contact_id__documents_get: {
+    input: {
+    path: {
+      /** Contact id. */
+      contact_id: number;
+    };
+    query?: {
+      /** Only documents in this folder. */
+      folder?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * GET /contacts/tags
+   * List Contact Tags
+   * tier: read · scope: contacts:read
+   */
+  list_contact_tags_contacts_tags_get: {
+    input: {
+    query?: {
+      /** Include archived tags. */
+      include_archived?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ContactTagListResponse_;
+  };
+  /**
+   * GET /contacts
+   * List Contacts
+   * tier: read · scope: contacts:read
+   */
+  list_contacts_contacts_get: {
+    input: {
+    query?: {
+      /** Page number (1-indexed) */
+      page?: number;
+      /** Items per page (max 200) */
+      limit?: number;
+      /** Filter by work email (exact match) */
+      email?: string | null;
+      /** Filter by list ID */
+      list_id?: number | null;
+      /** Filter by first or last name (partial match) */
+      name?: string | null;
+      /** Filter by job title (partial match) */
+      job_title?: string | null;
+      /** Filter by seniority level (exact match) */
+      seniority_level?: string | null;
+      /** Filter by company name (partial match) */
+      company_name?: string | null;
+      /** Filter by company ID */
+      company_id?: 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 job department (partial match) */
+      job_department?: string | null;
+      /** Filter by company industry (partial match) */
+      industry?: string | null;
+      /** When true, each contact 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_ContactListItem__;
+  };
+  /**
+   * GET /contacts/custom-column-definitions
+   * List Custom Column Definitions
+   * tier: read · scope: contacts:read
+   */
+  list_custom_column_definitions_contacts_custom_column_definitions_get: {
+    input: {
+    query?: {
+      /** `contact` or `company`. Anything else is refused. */
+      entity_type?: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * GET /duplicates/detection/runs
+   * List Duplicate Detection Runs
+   * tier: read · scope: contacts:read
+   */
+  list_duplicate_detection_runs_duplicates_detection_runs_get: {
+    input: {
+    query?: {
+      /** Only runs for this record type. */
+      entity_type?: ("contact" | "company" | "deal") | null;
+      /** How many runs, newest first. */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * GET /contacts/workflow-executions
+   * List Record Workflow Executions
+   * tier: read · scope: contacts:read
+   */
+  list_record_workflow_executions_contacts_workflow_executions_get: {
+    input: {
+    query: {
+      /** The list the row belongs to. */
+      list_id: number;
+      /** The row (contact) id. */
+      record_id: number;
+      /** Only runs of this workflow. */
+      workflow_id?: string | null;
+      /** Only this status. */
+      status?: string | null;
+      /** Include each run's step events. */
+      include_events?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * GET /contacts/searchable-fields
+   * List Searchable Fields
+   * tier: read · scope: contacts:read
+   */
+  list_searchable_fields_contacts_searchable_fields_get: {
+    input: {
+    query?: {
+      /** `contact` or `company`. Anything else is refused. */
+      entity_type?: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * POST /contacts/{contact_id}/merge
+   * Merge Contact
+   * tier: destructive · scope: contacts:delete
+   */
+  merge_contact_contacts__contact_id__merge_post: {
+    input: {
+    path: {
+      /** The contact that SURVIVES the merge. */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: MergeRecordRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /contacts/tags/merge
+   * Merge Contact Tags
+   * tier: write · scope: contacts:write
+   */
+  merge_contact_tags_contacts_tags_merge_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ContactTagMergeRequest;
+  };
+    output: ApiResponse_ContactTagWriteResult_;
+  };
+  /**
+   * POST /contacts/merge-filtered
+   * Merge Filtered Contacts
+   * tier: write · scope: contacts:write
+   */
+  merge_filtered_contacts_contacts_merge_filtered_post: {
+    input: {
+    query?: {
+      /** Optional per-column filter JSON, applied alongside `filter`. */
+      filterModel?: string | null;
+      /** Optional sort JSON. */
+      sortModel?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: MergeFilteredRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /contacts/workflow-executions/{execution_id}/pause
+   * Pause Record Workflow Execution
+   * tier: write · scope: contacts:write
+   */
+  pause_record_workflow_execution_contacts_workflow_executions__execution_id__pause_post: {
+    input: {
+    path: {
+      /** Workflow execution id. */
+      execution_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * GET /contacts/{contact_id}/merge/preview
+   * Preview Contact Merge
+   * tier: read · scope: contacts:read
+   */
+  preview_contact_merge_contacts__contact_id__merge_preview_get: {
+    input: {
+    path: {
+      /** The contact that SURVIVES the merge. */
+      contact_id: number;
+    };
+    query: {
+      /** The contact that would be merged AWAY. */
+      secondary: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /duplicates/settings/preview-detection-rule
+   * Preview Detection Rule
+   * tier: read · scope: contacts:read
+   */
+  preview_detection_rule_duplicates_settings_preview_detection_rule_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: PreviewDetectionRuleRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /contacts/{contact_id}/documents/types/{doc_type}/regenerate
+   * Regenerate Contact Document
+   * tier: billable · scope: enrichment:run
+   */
+  regenerate_contact_document_contacts__contact_id__documents_types__doc_type__regenerate_post: {
+    input: {
+    path: {
+      /** Contact id. */
+      contact_id: number;
+      /** Document type. */
+      doc_type: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /contacts/workflow-executions/{execution_id}/resume
+   * Resume Record Workflow Execution
+   * tier: write · scope: contacts:write
+   */
+  resume_record_workflow_execution_contacts_workflow_executions__execution_id__resume_post: {
+    input: {
+    path: {
+      /** Workflow execution id. */
+      execution_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /duplicates/detection/run
+   * Run Duplicate Detection
+   * tier: write · scope: contacts:write
+   */
+  run_duplicate_detection_duplicates_detection_run_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RunDetectionRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /contacts/workflow-executions/run
+   * Run Record Workflow
+   * tier: billable · scope: enrichment:run
+   */
+  run_record_workflow_contacts_workflow_executions_run_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RunRecordWorkflowRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /contacts/{contact_id}/documents/from-skill
+   * Save Skill Result To Contact
+   * tier: write · scope: contacts:write
+   */
+  save_skill_result_to_contact_contacts__contact_id__documents_from_skill_post: {
+    input: {
+    path: {
+      /** Contact primary key. */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: SaveSkillResultRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /duplicates/auto-merge
+   * Trigger Auto Merge
+   * tier: destructive · scope: contacts:delete
+   */
+  trigger_auto_merge_duplicates_auto_merge_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AutoMergeRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /contacts/tags/unassign
+   * Unassign Contact Tags
+   * tier: write · scope: contacts:write
+   */
+  unassign_contact_tags_contacts_tags_unassign_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ContactTagAssignRequest;
+  };
+    output: ApiResponse_ContactTagWriteResult_;
+  };
+  /**
+   * POST /contacts/unlock-info
+   * Unlock Contact Info
+   * tier: billable · scope: enrichment:run
+   */
+  unlock_contact_info_contacts_unlock_info_post: {
+    input: {
+    query?: {
+      /** Per-column filter JSON, resolved against `list_id`. */
+      filterModel?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: UnlockContactInfoRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * PATCH /contacts/{contact_id}
+   * Update Contact
+   * tier: write · scope: contacts:write
+   */
+  update_contact_contacts__contact_id__patch: {
+    input: {
+    path: {
+      /** Contact ID */
+      contact_id: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ContactUpdateRequest;
+  };
+    output: ApiResponse_dict_;
+  };
+  /**
+   * PUT /contacts/{contact_id}/documents/{document_id}
+   * Update Contact Document
+   * tier: write · scope: contacts:write
+   */
+  update_contact_document_contacts__contact_id__documents__document_id__put: {
+    input: {
+    path: {
+      /** Contact id. */
+      contact_id: number;
+      /** Document id. */
+      document_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ContactDocumentUpdateRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * PATCH /contacts/tags/{tag_id}
+   * Update Contact Tag
+   * tier: write · scope: contacts:write
+   */
+  update_contact_tag_contacts_tags__tag_id__patch: {
+    input: {
+    path: {
+      /** Tag id. */
+      tag_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ContactTagUpdateRequest;
+  };
+    output: ApiResponse_ContactTag_;
+  };
+  /**
+   * PUT /duplicates/settings
+   * Update Duplicate Settings
+   * tier: write · scope: contacts:write
+   */
+  update_duplicate_settings_duplicates_settings_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: Record<string, unknown>;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /contacts/verify-email
+   * Verify Contact Emails
+   * tier: billable · scope: enrichment:run
+   */
+  verify_contact_emails_contacts_verify_email_post: {
+    input: {
+    query?: {
+      /** Restrict a filtered selection to this list. */
+      list_id?: number | null;
+      /** Per-column filter JSON. With `list_id`, verifies every matching contact instead of the ids in the body. */
+      filterModel?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: VerifyContactEmailRequest;
+  };
+    output: ApiResponse_CrmCollectionPayload_;
+  };
+  /**
+   * POST /contacts/verify-email/async
+   * Verify Contact Emails Async
+   * tier: billable · scope: enrichment:run
+   */
+  verify_contact_emails_async_contacts_verify_email_async_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: VerifyContactEmailAsyncRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * POST /contacts/withdraw-from-sequences
+   * Withdraw Contacts From Sequences
+   * tier: write · scope: contacts:write
+   */
+  withdraw_contacts_from_sequences_contacts_withdraw_from_sequences_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: WithdrawFromSequencesRequest;
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+}
+
+// 68 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_ContactBulkGetResponse_ {
+  data: ContactBulkGetResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ContactCreateResponse_ {
+  data: ContactCreateResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ContactRelatedBatchResponse_ {
+  data: ContactRelatedBatchResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ContactResponse_ {
+  data: ContactResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ContactTagListResponse_ {
+  data: ContactTagListResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ContactTagWriteResult_ {
+  data: ContactTagWriteResult;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ContactTag_ {
+  data: ContactTag;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_CreateContactColumnResponse_ {
+  data: CreateContactColumnResponse;
+  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_ContactListItem__ {
+  data: Array<ContactListItem>;
+  pagination?: PaginationMeta | null;
+}
+
+/** Mirrors `ApproveRequest`. The app refuses anything but these two decisions. */
+export interface ApproveExecutionRequest {
+  /** Approve or reject the paused step. */
+  decision: "approve" | "reject";
+  /** Recorded with a rejection. */
+  reason?: string | 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;
+}
+
+/**
+ * Run auto-merge once. NOT REVERSIBLE unless you undo each merge.
+ *
+ * Honours the org's own auto-merge and shadow-mode settings: with either
+ * disabled the response SAYS SO instead of failing, so a 200 does not by
+ * itself mean records were merged. Send `dry_run=true` first.
+ */
+export interface AutoMergeRequest {
+  /** Report what would merge without merging it. */
+  dry_run?: boolean;
+  /** Object to merge. */
+  entity_type: "contact" | "company";
+}
+
+/**
+ * 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";
+
+/** One contact: the full record, or `found: false`. */
+export interface ContactBulkGetItem {
+  /** The same record `GET /contacts/{contact_id}` returns. Null when not found. */
+  contact?: ContactResponse | null;
+  contact_id: number;
+  /** False when the contact does not exist or is outside this key's scope (indistinguishable on purpose, like the per-contact 404). */
+  found: boolean;
+}
+
+/** Which contacts to read in full. */
+export interface ContactBulkGetRequest {
+  /** Up to 100 contact ids, the ids `GET /contacts` returns. Duplicates are read once; the response keeps first-seen order. */
+  contact_ids: Array<number>;
+  /** When true, each found contact includes a `custom_fields` object keyed by column slug, as `GET /contacts/{contact_id}?include_custom_fields=true` does. */
+  include_custom_fields?: boolean;
+}
+
+export interface ContactBulkGetResponse {
+  items?: Array<ContactBulkGetItem>;
+}
+
+export interface ContactCompanySummary {
+  city?: string | null;
+  country?: string | null;
+  domain?: string | null;
+  employee_count?: string | null;
+  id?: number | null;
+  industry?: string | null;
+  linkedin_url?: string | null;
+  logo_url?: string | null;
+  name?: string | null;
+  state?: string | null;
+  website?: string | null;
+}
+
+/** Request body for creating contacts. */
+export interface ContactCreateRequest {
+  /** City */
+  city?: string | null;
+  /** Company domain for matching */
+  company_domain?: string | null;
+  /** Existing company id (mashup_companies.id) to attach */
+  company_id?: number | null;
+  /** Country */
+  country?: string | null;
+  /** When true, custom_fields keys that match no existing column are created as NEW custom columns (list-scoped when list_id is set) and then written. */
+  create_missing_fields?: boolean;
+  /** Custom column values keyed by the column's display title (e.g. 'Followup 1'), its slug (e.g. 'udo_followup_1_ab12cd34'), or a case/space variant of the title. Keys matching no existing column are reported in the response's `custom_fields.ignored` unless `create_missing_fields` is true. */
+  custom_fields?: (Record<string, string | null>) | null;
+  /** Direct phone number */
+  direct_phone?: string | null;
+  /** Contact first name */
+  first_name?: string | null;
+  /** Department */
+  job_department?: string | null;
+  /** Job title */
+  job_title?: string | null;
+  /** Contact last name */
+  last_name?: string | null;
+  /** LinkedIn profile URL */
+  linkedin_url?: string | null;
+  /** Optional target list ID. When provided, the contact is added to this list after it is created; omit to create the contact without a list. */
+  list_id?: number | null;
+  /** Mobile phone number */
+  mobile_phone?: string | null;
+  /** Personal email addresses */
+  personal_emails?: string | null;
+  /** Seniority level */
+  seniority_level?: string | null;
+  /** State/Province */
+  state?: string | null;
+  /** Work email address */
+  work_email?: string | null;
+}
+
+export interface ContactCreateResponse {
+  company_attached?: boolean;
+  contact_id?: number | null;
+  count: number;
+  custom_fields?: CustomFieldWriteReport;
+  merged?: boolean;
+  status: string;
+  validation_errors?: Array<string>;
+}
+
+/** Mirrors `campaign_builder.models.contact_documents.UpdateContactDocumentRequest`. */
+export interface ContactDocumentUpdateRequest {
+  /** Replacement document body. */
+  content?: string | null;
+  /** Replacement structured payload. */
+  structured_data?: Record<string, unknown> | null;
+}
+
+/** Lighter contact representation for list endpoints. */
+export interface ContactListItem {
+  city?: string | null;
+  company_id?: number | null;
+  country?: string | null;
+  custom_fields?: (Record<string, string | null>) | null;
+  direct_phone?: string | null;
+  first_name?: string | null;
+  id?: number | null;
+  job_department?: string | null;
+  job_title?: string | null;
+  last_name?: string | null;
+  linkedin_url?: string | null;
+  mobile_phone?: string | null;
+  owner_id?: string | null;
+  owner_name?: string | null;
+  seniority_level?: string | null;
+  state?: string | null;
+  work_email?: string | null;
+}
+
+/** Which contacts, and which of their related records, to read in one call. */
+export interface ContactRelatedBatchRequest {
+  /** Up to 100 contact ids, the same ids the per-contact routes take. Duplicates are read once; the response keeps first-seen order. */
+  contact_ids: Array<number>;
+  /** Related records to return per contact. `sequences` matches `GET /contacts/{contact_id}/sequences`; `lists` matches `GET /contacts/{contact_id}/lists` (keyed on the contact primary key). */
+  include?: Array<"sequences" | "lists">;
+}
+
+export interface ContactRelatedBatchResponse {
+  items?: Array<ContactRelatedItem>;
+}
+
+/** One contact's related records. A field is present only when requested. */
+export interface ContactRelatedItem {
+  contact_id: number;
+  /** False when the contact does not exist or is outside this key's scope (indistinguishable on purpose, like the per-contact 404). */
+  found: boolean;
+  lists?: Array<Record<string, unknown>> | null;
+  sequences?: Array<Record<string, unknown>> | null;
+}
+
+export interface ContactResponse {
+  about?: string | null;
+  city?: string | null;
+  company?: ContactCompanySummary | null;
+  confidence_score?: number | null;
+  country?: string | null;
+  created_at?: string | null;
+  custom_fields?: (Record<string, string | null>) | null;
+  direct_phone?: string | null;
+  facebook_url?: string | null;
+  first_name?: string | null;
+  full_name?: string | null;
+  id: number;
+  job_department?: string | null;
+  job_title?: string | null;
+  last_name?: string | null;
+  linkedin_url?: string | null;
+  meta_data?: Record<string, unknown> | null;
+  mobile_phone?: string | null;
+  personal_emails?: unknown | null;
+  seniority_level?: string | null;
+  state?: string | null;
+  twitter_url?: string | null;
+  updated_at?: string | null;
+  work_email?: string | null;
+}
+
+export interface ContactTag {
+  archived?: boolean | null;
+  color?: string | null;
+  /** Contacts currently carrying the tag. */
+  contact_count?: number | null;
+  description?: string | null;
+  id?: string | null;
+  name?: string | null;
+  [key: string]: unknown;
+}
+
+export interface ContactTagAssignRequest {
+  /** Contacts to tag. */
+  contact_ids?: Array<number>;
+  tag_ids: Array<string>;
+}
+
+export interface ContactTagCreateRequest {
+  /** Six-digit hex colour, e.g. `#4F46E5`. */
+  color?: string | null;
+  description?: string | null;
+  name: string;
+}
+
+export interface ContactTagListResponse {
+  tags?: Array<ContactTag>;
+  total?: number;
+  [key: string]: unknown;
+}
+
+export interface ContactTagMergeRequest {
+  /** Tags to fold in. Removed on success. */
+  source_tag_ids: Array<string>;
+  /** Tag that survives and absorbs the assignments. */
+  target_tag_id: string;
+}
+
+/** Every field is optional; omit one to leave it untouched. */
+export interface ContactTagUpdateRequest {
+  /** Archive without deleting. */
+  archived?: boolean | null;
+  color?: string | null;
+  description?: string | null;
+  name?: string | null;
+}
+
+/** Whatever the handler reports about a write - counts, ids, or both. */
+export type ContactTagWriteResult = Record<string, unknown>;
+
+/** Request body for updating a contact. All fields optional (partial update). */
+export interface ContactUpdateRequest {
+  city?: string | null;
+  company_domain?: string | null;
+  company_id?: number | null;
+  country?: string | null;
+  direct_phone?: string | null;
+  first_name?: string | null;
+  job_department?: string | null;
+  job_title?: string | null;
+  last_name?: string | null;
+  linkedin_url?: string | null;
+  mobile_phone?: string | null;
+  seniority_level?: string | null;
+  state?: string | null;
+  work_email?: string | null;
+}
+
+/**
+ * Request body for `POST /contacts/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 CreateContactColumnRequest {
+  /** 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. 'Lead Score') */
+  title: string;
+}
+
+/**
+ * Response shape for `POST /contacts/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 CreateContactColumnResponse {
+  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>;
+
+/**
+ * How a write path handled the request's custom (dynamic) column keys.
+ *
+ * Shared by every Developer API write surface that accepts custom columns
+ * (``POST /contacts``, ``PUT /contacts/assert[/batch]``,
+ * ``PUT /companies/assert[/batch]``).
+ *
+ * Every field defaults to empty, so a client that ignores this object sees no
+ * behavioural change. It exists because these keys were previously dropped
+ * with NO caller-visible signal — the only trace was a server-side
+ * ``logger.warning`` in ``append_to_audience``.
+ */
+export interface CustomFieldWriteReport {
+  /** Caller keys for which a NEW custom column was created by this request. */
+  created?: Array<string>;
+  /** Caller keys that matched no custom column and were NOT written. Create the column first (POST /fields) or pass create_missing_fields=true. */
+  ignored?: Array<string>;
+  /** Caller keys that resolved to a custom column and were written. */
+  written?: Array<string>;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * Page through contacts, optionally projecting a narrow column set.
+ *
+ * `mapping_columns` is not only a smaller payload: naming a narrow set lets
+ * the planner drop joins the full row would force, so it is materially
+ * cheaper on a wide org.
+ */
+export interface FetchContactsRequest {
+  /** Serialized per-column filter JSON. Omit for no filter. */
+  filter?: string | null;
+  /** Records per page. */
+  limit?: number;
+  /** Columns to return. Omit for every column. */
+  mapping_columns?: Array<string> | null;
+  /** Page number (1-indexed). */
+  page?: number;
+}
+
+/**
+ * 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;
+}
+
+/** 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;
+}
+
+/**
+ * Dry-run a duplicate-detection rule. Writes nothing.
+ *
+ * Returns how many pairs the rule would match plus a small sample, which is
+ * the only way to size a rule before auto-merge starts acting on it.
+ */
+export interface PreviewDetectionRuleRequest {
+  /** Override the default confidence bucket. */
+  confidence_bucket?: ("high" | "medium" | "low") | null;
+  /** Object the rule matches on. */
+  entity_type: "contact" | "company" | "deal";
+  /** Column the rule compares. */
+  field: string;
+  /** How two values are considered equal. */
+  match_mode: "exact" | "normalized" | "fuzzy_levenshtein" | "domain_match" | "phone_e164" | "linkedin_handle";
+  /** Name for the rule being previewed. */
+  rule_name: string;
+  /** Override the platform default score for this rule. */
+  score?: number | null;
+  /** Platform rule template the rule is built from. */
+  template: string;
+}
+
+/**
+ * Resolve profile photos for a batch of LinkedIn URLs.
+ *
+ * Returns an entry only for contacts that have an allow-listed https photo,
+ * so a missing key means "no photo", not "lookup failed".
+ */
+export interface ProfilePicturesRequest {
+  /** LinkedIn profile URLs (deduplicated, max 200). */
+  linkedin_urls?: Array<string>;
+}
+
+/**
+ * Read every column value for ONE row, resolved against a list.
+ *
+ * The list decides whether `record_id` is read as a contact or a company,
+ * and which list-scoped custom columns are in play - which is why it is
+ * required rather than inferred.
+ */
+export interface RecordColumnValuesRequest {
+  /** List the record is read through. */
+  list_id: number;
+  /** Record primary key. */
+  record_id: number;
+}
+
+/** Mirrors `duplicates.interfaces.router._RunDetectionRequest`. */
+export interface RunDetectionRequest {
+  /** What to scan. */
+  entity_type: "contact" | "company" | "deal";
+}
+
+/** Mirrors `RunWorkflowRequest`. `run_mode` is closed to the app's three values. */
+export interface RunRecordWorkflowRequest {
+  /** List (workbench) the workflow belongs to. */
+  list_id: number;
+  /** Rows to run it on, for `selected`. */
+  record_ids: Array<number>;
+  /** Which rows to run on. */
+  run_mode?: "selected" | "filtered" | "all";
+  /** Workflow to run. */
+  workflow_id: string;
+}
+
+/** 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";
+}
+
+/**
+ * Reveal withheld contact details. SPENDS CREDITS.
+ *
+ * Charges per contact actually unlocked. Already-unlocked contacts are not
+ * charged again, so re-sending the same ids is safe but not free to compute.
+ */
+export interface UnlockContactInfoRequest {
+  /** Resolve the complete matching set server-side. */
+  allMatching?: boolean;
+  /** Contacts to unlock (max 1000). */
+  contact_ids?: Array<number> | null;
+  /** Per-column filters. */
+  filterModel?: Record<string, unknown>;
+  /** Unlock the contacts in this list. */
+  list_id?: number | null;
+  /** Advanced AND/OR filter tree. */
+  segmentFilter?: SegmentFilterGroup | null;
+}
+
+/**
+ * Queue verification for a LIST or a filtered selection.
+ *
+ * SPENDS CREDITS, and unlike the synchronous route the size is not known
+ * when the call returns - `all_matching` resolves the selection server-side.
+ */
+export interface VerifyContactEmailAsyncRequest {
+  /** Resolve the complete matching set server-side, not just a page. */
+  allMatching?: boolean;
+  /** Per-column filters, keyed by column name. */
+  filterModel?: Record<string, unknown>;
+  /** Restrict the selection to this list. */
+  list_id?: number | null;
+  /** Advanced cross-column AND/OR filter tree. */
+  segmentFilter?: SegmentFilterGroup | null;
+}
+
+/**
+ * Re-check the deliverability of a named batch of contacts' emails.
+ *
+ * SPENDS CREDITS: each address is sent to the email-verification service.
+ * Use the async variant for a whole list or a filtered selection.
+ */
+export interface VerifyContactEmailRequest {
+  /** Contact primary keys (max 1000). Empty verifies nothing. */
+  contact_pks?: Array<number>;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Take contacts OUT of a sequence. They stop receiving its steps.
+ *
+ * `remove_all=true` withdraws them from EVERY sequence they are enrolled
+ * in and ignores `sequence_id`; that is the wider blast radius of the two
+ * and it is never the default.
+ */
+export interface WithdrawFromSequencesRequest {
+  /** Contact primary keys to withdraw (max 5000). */
+  contact_ids?: Array<number>;
+  /** Withdraw from EVERY enrolled sequence. Ignores `sequence_id`. */
+  remove_all?: boolean;
+  /** Sequence to withdraw from. Required unless `remove_all` is true. */
+  sequence_id?: string | null;
+  /** Origin label recorded on the resulting event. */
+  source?: string | null;
+  /** Terminal state to record: removed | completed | not_interested. */
+  target_state?: string | null;
+}