> ## Documentation Index > Fetch the complete documentation index at: https://docs.getsales.io/llms.txt > Use this file to discover all available pages before exploring further. # Import data source > Confirm the column mapping and start parsing a csv source: the only draft to active transition, the agent's entry point after the UI's upload-csv hands over a draft sid. It is the last word on what the rows become (object_type) and on what the import does with them (mode): a draft holds nothing yet, so both override what the upload said. The mapping is a column preset, not an ingestion filter: it decides which grid columns the import materializes and nothing else, so it may cover no identity column or be [] entirely; every row is staged whole and the dedup ladder uses whatever identity the record carries. mode=update needs match (the existing-row lookup key and the CSV column carrying it); a row that matches nothing fails match_not_found, update never creates. Async: the parser streams the file in 1k-row batches, each row becoming a pending data_source_items row promoted on its own. The async ref rides result.pending (expected_completion_seconds, webhook_events, polling_hint), not a top-level pending[]: poll get_data_source with include data_source_items_counts until status is completed or failed, then report the funnel. Not idempotent: a repeat on the now-active source is 409 invalid_transition, a non-csv source 422 on sid; an exhausted contact or credit allowance is 402 payment_required. When NOT: the search and webhook kinds (born active at create); re-running failed rows (an import playtable run). Contract: - MCP tool `import_data_source`, registry package `mcp.playtables/data_sources`, mount `playtables.sources`. - Operation `action`, response envelope `action`. - Flags: none. ## OpenAPI ````yaml /api-reference/playtables/openapi.yaml post /api/data-sources/{sid}/import openapi: 3.0.3 info: title: 'GetSales public contract: gs.service.playtables' description: >- The data platform and the outreach engine: tables of people and companies, their enrichment columns, cells and runs, the data sources that feed them, sender profiles, the stoplist, the activity feed, the credit ledger, and the multichannel workflows with their per-person journeys and tasks. GENERATED. This document is projected from the Zod MCP tool registry in `product/mcp/gs.mcp` (one tool per public endpoint, 1:1). Do not edit it by hand; edit the tool definition and regenerate with `pnpm openapi:public`. Surface: the public `/api` contract of `gs.service.playtables`, 142 operations. This is the only OpenAPI document the platform publishes. Internal (`/internal`) and health endpoints are deliberately absent: they are not part of any contract, they can change without notice, and the service source is their only description. Conventions: - Auth is a bearer JWT, optionally narrowed by the `Team-SID` header. - Every success body is an MCP envelope: `success: true` plus one typed `operation` shape (`search`, `get`, `create`, `update`, `delete`, `metrics`, `group_by`, `action`), and a `meta` block with `trace_id` for support. - Every failure is the same `McpError` envelope with a code from a fixed 16-code taxonomy, so a client maps errors once. - Lists page with `page_size` (0 to 500, default 50) plus an opaque forward `cursor`; `page_size: 0` returns counts only. - On `GET` and `DELETE`, object-valued query parameters (`filter`, `sort`) travel as JSON text and array-valued ones repeat as `name[]=value`. - The MCP-only `_meta` field (usage analytics) never reaches the backend and is not part of this contract. version: '1.0' contact: name: GetSales url: https://getsales.io email: support@getsales.io license: name: Proprietary url: https://getsales.io/terms servers: - url: https://beta.getsales.io/playtables/v1 description: >- Production (the gateway path on the beta ring; the origin is provisioned per DEPLOY_MAP.md) security: - BearerJwt: [] TeamSid: [] tags: - name: activities description: >- Registry package `mcp.playtables/activities`, served on MCP mount `playtables.journeys`. - name: activity_objects description: >- Registry package `mcp.playtables/activity_objects`, served on MCP mount `playtables.people`. - name: companies description: >- Registry package `mcp.playtables/companies`, served on MCP mount `playtables.people`. - name: credit_ledger_entries description: >- Registry package `mcp.playtables/credit_ledger_entries`, served on MCP mount `id.billing`. - name: data_source_items description: >- Registry package `mcp.playtables/data_source_items`, served on MCP mount `playtables.sources`. - name: data_sources description: >- Registry package `mcp.playtables/data_sources`, served on MCP mount `playtables.sources`. - name: notes description: >- Registry package `mcp.playtables/notes`, served on MCP mount `playtables.pipeline`. - name: people description: >- Registry package `mcp.playtables/people`, served on MCP mount `playtables.people`. - name: pipeline_stages description: >- Registry package `mcp.playtables/pipeline_stages`, served on MCP mount `playtables.pipeline`. - name: plays description: >- Registry package `mcp.playtables/plays`, served on MCP mount `playtables.pipeline`. - name: playtable_field_values description: >- Registry package `mcp.playtables/playtable_field_values`, served on MCP mount `playtables.columns`. - name: playtable_fields description: >- Registry package `mcp.playtables/playtable_fields`, served on MCP mount `playtables.columns`. - name: playtable_runs description: >- Registry package `mcp.playtables/playtable_runs`, served on MCP mount `playtables.columns`. - name: playtable_views description: >- Registry package `mcp.playtables/playtable_views`, served on MCP mount `playtables.tables`. - name: playtables description: >- Registry package `mcp.playtables/playtables`, served on MCP mount `playtables.tables`. - name: result_pages description: >- Registry package `mcp.playtables/result_pages`, served on MCP mount `playtables.tables`. - name: sender_profiles description: >- Registry package `mcp.playtables/sender_profiles`, served on MCP mount `playtables.sources`. - name: stoplist_entries description: >- Registry package `mcp.playtables/stoplist_entries`, served on MCP mount `playtables.stoplist`. - name: tags description: >- Registry package `mcp.playtables/tags`, served on MCP mount `playtables.pipeline`. - name: workflow_attachments description: >- Registry package `mcp.playtables/workflow_attachments`, served on MCP mount `playtables.workflows`. - name: workflow_records description: >- Registry package `mcp.playtables/workflow_records`, served on MCP mount `playtables.journeys`. - name: workflow_sources description: >- Registry package `mcp.playtables/workflow_sources`, served on MCP mount `playtables.workflows`. - name: workflow_tasks description: >- Registry package `mcp.playtables/workflow_tasks`, served on MCP mount `playtables.journeys`. - name: workflow_versions description: >- Registry package `mcp.playtables/workflow_versions`, served on MCP mount `playtables.workflows`. - name: workflows description: >- Registry package `mcp.playtables/workflows`, served on MCP mount `playtables.workflows`. paths: /api/data-sources/{sid}/import: post: tags: - data_sources summary: Import data source description: >- Confirm the column mapping and start parsing a csv source: the only draft to active transition, the agent's entry point after the UI's upload-csv hands over a draft sid. It is the last word on what the rows become (object_type) and on what the import does with them (mode): a draft holds nothing yet, so both override what the upload said. The mapping is a column preset, not an ingestion filter: it decides which grid columns the import materializes and nothing else, so it may cover no identity column or be [] entirely; every row is staged whole and the dedup ladder uses whatever identity the record carries. mode=update needs match (the existing-row lookup key and the CSV column carrying it); a row that matches nothing fails match_not_found, update never creates. Async: the parser streams the file in 1k-row batches, each row becoming a pending data_source_items row promoted on its own. The async ref rides result.pending (expected_completion_seconds, webhook_events, polling_hint), not a top-level pending[]: poll get_data_source with include data_source_items_counts until status is completed or failed, then report the funnel. Not idempotent: a repeat on the now-active source is 409 invalid_transition, a non-csv source 422 on sid; an exhausted contact or credit allowance is 402 payment_required. When NOT: the search and webhook kinds (born active at create); re-running failed rows (an import playtable run). Contract: - MCP tool `import_data_source`, registry package `mcp.playtables/data_sources`, mount `playtables.sources`. - Operation `action`, response envelope `action`. - Flags: none. operationId: import_data_source parameters: - name: sid in: path required: true description: >- The draft source (ds_sc_…) - must be status=draft, type=csv; anything else → 409 invalid_transition or 422. schema: type: string minLength: 18 maxLength: 18 pattern: ^ds_sc_ description: >- The draft source (ds_sc_…) - must be status=draft, type=csv; anything else → 409 invalid_transition or 422. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ImportDataSourceRequest' responses: '200': description: '`action` success envelope.' content: application/json: schema: $ref: '#/components/schemas/ImportDataSourceResponse' 4XX: $ref: '#/components/responses/McpClientError' 5XX: $ref: '#/components/responses/McpServerError' components: schemas: ImportDataSourceRequest: type: object description: Request body of `import_data_source`. properties: field_mapping: type: array items: type: object properties: source: type: string minLength: 1 maxLength: 512 description: >- CSV column index as a string ("3") or JSON path into the webhook body ("contact.email"). target_kind: type: string enum: - people_attribute - company_attribute - field_slug description: people_attribute | company_attribute | field_slug. target: type: string minLength: 1 maxLength: 255 description: >- Attribute key (people / company) or a playtable field slug in the target table. name: type: string nullable: true minLength: 1 maxLength: 255 description: >- Display name for the column a field_slug target creates (the header renamed in the mapping UI); null = the CSV header names it. Ignored for the attribute kinds and for fields that already exist. required: - source - target_kind - target description: >- May be []: a column preset, not a filter (mapping nothing stages every row whole). A field_slug target with no live column materializes one (named by name, else the CSV header); item.field_mapping is authoritative, a clashing slug rewritten. object_type: type: string enum: - people - company description: >- Override what the rows become: people | company. Absent = what the upload said. mode: type: string enum: - create - update description: >- Override what the import does: create (new objects) | update (resolve an existing object by `match` and apply the mapped attributes). Absent = what the upload said. match: type: object properties: field: type: string enum: - person_sid - email - ln_nickname - company_sid - domain - name description: >- Existing-row lookup key. people: person_sid | email (work or personal) | ln_nickname (a profile URL reduces to the slug). company: company_sid | ln_nickname | domain | name. Values are normalized the same way the stored identifiers are. csv_column: type: integer minimum: 0 description: >- CSV column index carrying the match value (same indexing as field_mapping.source). required: - field - csv_column description: >- Required when the resulting mode is update, prohibited when it is create. on_duplicate: type: string enum: - skip - move description: Override before start; default = the draft's stored policy. add_tags_to_duplicate: type: boolean description: >- Override before start: merge tag_sids onto matched duplicates; default = the draft's stored policy. qualify: type: object nullable: true properties: 'on': type: boolean description: >- The switch. `on` with no criterion is refused (422 on qualify.criterion, rule required_if). criterion: type: string nullable: true minLength: 1 maxLength: 2000 description: >- Who passes, in the user's words ("a decision maker at a marketing agency, not a freelancer"). Trimmed; null while the check is off. required: - 'on' - criterion additionalProperties: false description: >- The last word on the gate too: the block to run, null to switch it off, absent = what the upload said. required: - field_mapping ImportDataSourceResponse: type: object properties: success: type: boolean enum: - true operation: type: string enum: - action action: type: string description: kebab-case verb; matches the route segment. item: type: object nullable: true properties: sid: type: string team_sid: type: string playtable_sid: type: string nullable: true description: >- pt_tb_… target table, required on every create; becomes null only when the target playtable is deleted (the source auto-pauses, status_reason=playtable_deleted). name: type: string description: >- min 1, max 255. Defaulted from the kind and its link when omitted on create ("Sales Navigator saved search", "My conversations", "AI search: CMOs in DACH"). type: type: string enum: - ai_search - sender_search - post_engagement - find_people - csv - webhook description: >- [ro] The source kind: ai_search | sender_search | post_engagement | find_people | csv | webhook. Immutable after create. object_type: type: string enum: - people - company description: >- What promoted items become: people | company. An input of create, not a derivation of type; [ro] once the source is past draft (a csv draft's import step may still change it). sender_profile_sid: type: string nullable: true description: >- ub_sp_… the sender profile whose own LinkedIn account collects. Required for type=sender_search and post_engagement, null for every other kind - see ./sender_profiles.md. ingest_key: type: string nullable: true description: >- type=webhook only: the 40-char capability secret in the ingest URL ({api_base}/external/ingest/{ingest_key}). Stored plaintext by design so the URL stays re-viewable; rotate-ingest-key revokes it. null for every other kind. payload: anyOf: - type: object properties: platform: type: string enum: - linkedin - sales_navigator - recruiter description: >- ai_search (link mode) and sender_search: which LinkedIn product the link opens in. surface: type: string enum: - search - saved_search - list - post - my_network - messenger description: >- ai_search (link mode) and sender_search: what kind of list the link is. repeat: type: string nullable: true enum: - hourly - daily - weekly - monthly description: >- sender_search, post_engagement: the rerun interval; absent or null = runs once. mode: type: string enum: - create - update description: 'csv: what the import does with its rows.' target: type: string enum: - post - person - company description: >- post_engagement: what the source watches; the axis beside it names it (post.urn, person.ln_nickname, or company.ln_nickname with ln_id, name and logo_url once the walk resolved the page). A link is never stored: rebuild it from the axis. window: anyOf: - type: object properties: days: anyOf: - type: number enum: - 7 - type: number enum: - 30 - type: number enum: - 90 required: - days additionalProperties: false - type: object properties: since: type: string pattern: ^\d{4}-\d{2}-\d{2}$ required: - since additionalProperties: false description: >- post_engagement, a person or a company: the window the posts are read from. relevance: type: object properties: prompt: type: string required: - prompt description: >- post_engagement: the AI post filter; absent = every post is walked. collect: type: object properties: reactions: type: boolean comments: type: boolean reposts: type: boolean additionalProperties: false description: 'post_engagement: the feeds the walk collects.' posts: type: array items: type: object properties: urn: type: string title: type: string published_at: type: string nullable: true verdict: type: string enum: - match - skip verdict_reason: type: string required: - urn description: >- post_engagement: the posts the walk read, newest first, each with its title (the first line), text, author, published_at, counts, the filter's verdict with the reason of a skip, and the walk's cursor per feed (feeds.reactors | comments | resharers: {cursor} or {done: true}). - type: array items: {} description: >- Kind-discriminated config JSON, validated per kind server-side. ai_search: prompt | url + platform + surface, filters + engine (the stored plan), plan_chips / plan_warnings, next_page / latest_page (the walk cursor), collect_error (what stopped the walk: kind transient | refused, http, code, reason, message, fields; with status_reason collect_failed | collect_interrupted). sender_search: url + platform + surface, repeat, and the collector's own cursor (next_page / latest_page for the Recruiter walker, poll_since / poll_cursor / poll_max for the network and inbox pollers; the bus-served surfaces keep none). find_people: company_sids, next_index, per_company_limit, prompt, filters + engine. csv: file_path, file_type, mode, total_rows, config, match. webhook: records_path. post_engagement (2026-10-28): target + post {urn} | person {ln_nickname; ln_id, ln_member_id, name once resolved} | company {ln_nickname, ln_id, name, logo_url}, window, relevance, collect, repeat, and the walk's own state: stage (posts | judge | engage | done), posts (what it read, with verdicts and feed cursors), cycle, next_page / latest_page, migrated_from on a row born as a search with a post link before the kind existed. field_mapping: type: array nullable: true items: type: object properties: source: type: string minLength: 1 maxLength: 512 description: >- CSV column index as a string ("3") or JSON path into the webhook body ("contact.email"). target_kind: type: string enum: - people_attribute - company_attribute - field_slug description: people_attribute | company_attribute | field_slug. target: type: string minLength: 1 maxLength: 255 description: >- Attribute key (people / company) or a playtable field slug in the target table. name: type: string nullable: true minLength: 1 maxLength: 255 description: >- Display name for the column a field_slug target creates (the header renamed in the mapping UI); null = the CSV header names it. Ignored for the attribute kinds and for fields that already exist. required: - source - target_kind - target description: >- source→target entries: set at import for csv (and may be []), an optional override for webhook (absent = attribute auto-detect at promotion), forbidden for the three search kinds (their collector emits the canonical parser shape). tag_sids: type: array nullable: true items: type: string description: >- cr_tg_… each - tags applied to every promoted object - see ./tags.md. qualify: type: object nullable: true properties: 'on': type: boolean description: >- The switch. `on` with no criterion is refused (422 on qualify.criterion, rule required_if). criterion: type: string nullable: true minLength: 1 maxLength: 2000 description: >- Who passes, in the user's words ("a decision maker at a marketing agency, not a freelancer"). Trimmed; null while the check is off. required: - 'on' - criterion additionalProperties: false description: >- The source gate, "Check on save": null = no check. The promotion reads it before a row is born (see ./data_source_items.md Lifecycle 6.5). on_duplicate: type: string enum: - skip - move description: Duplicate-person policy; default 'skip'. add_tags_to_duplicate: type: boolean description: Merge tag_sids onto matched duplicates; default false. status: type: string enum: - draft - active - paused - completed - failed status_reason: type: string nullable: true description: >- Reason token behind a paused or failed state (max 2048): playtable_deleted, sales_nav_required, recruiter_required, recruiter_reauth_required, executor_account_missing, plan_failed, collect_failed, collect_interrupted, post_unavailable (the post could not be read: deleted or private), target_not_found (no page at the slug), allowance_exhausted (the AI post filter ran out of credits; paused), … next_collect_at: type: string nullable: true description: >- ISO 8601 UTC - the collect clock of a search kind, advanced by checkpoints and the repeat interval. null for csv and webhook, and nulled on a bus-served sender search once its scrapes are provisioned (gtm-api owns the cadence from then on). created_by: type: object properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string nullable: true team_sid: type: string actor_name: type: string nullable: true description: >- The OAuth client that acted ("Claude", "n8n"); null for a user, an API key or a system job. oauth_client_sid: type: string nullable: true description: The acting OAuth client (id_oc_*); null off the OAuth path. reason: type: string nullable: true description: >- Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise. permissions: type: object additionalProperties: {} description: >- Internal audit context: the grant set the actor held at write time. Not a contract. cluster_id: type: integer nullable: true description: 'Internal audit context: the cluster that served the write.' trace_id: type: string nullable: true description: >- Internal audit context: the trace id of the request that wrote the row. required: - actor_type - actor_sid - team_sid - permissions deleted_by: type: object nullable: true properties: actor_type: type: string enum: - user - support - api_key - system - agent actor_sid: type: string nullable: true team_sid: type: string actor_name: type: string nullable: true description: >- The OAuth client that acted ("Claude", "n8n"); null for a user, an API key or a system job. oauth_client_sid: type: string nullable: true description: The acting OAuth client (id_oc_*); null off the OAuth path. reason: type: string nullable: true description: >- Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise. permissions: type: object additionalProperties: {} description: >- Internal audit context: the grant set the actor held at write time. Not a contract. cluster_id: type: integer nullable: true description: 'Internal audit context: the cluster that served the write.' trace_id: type: string nullable: true description: >- Internal audit context: the trace id of the request that wrote the row. required: - actor_type - actor_sid - team_sid - permissions created_at: type: string updated_at: type: string deleted_at: type: string nullable: true required: - sid - team_sid - playtable_sid - name - type - object_type - sender_profile_sid - ingest_key - payload - field_mapping - tag_sids - qualify - on_duplicate - add_tags_to_duplicate - status - status_reason - next_collect_at - created_by - deleted_by - created_at - updated_at - deleted_at result: type: object properties: total_rows: type: integer minimum: 0 description: CSV data rows detected (header excluded). pending: type: object properties: expected_completion_seconds: type: integer minimum: 0 description: ~ceil(total_rows / 1000) * 60. webhook_events: type: array items: anyOf: - type: string enum: - data-sources.completed - type: string enum: - data-sources.failed minItems: 2 maxItems: 2 description: Terminal webhooks that close this parse. polling_hint: type: string description: >- e.g. "poll data_sources.get(sid, include=[data_source_items_counts]) until status is terminal". required: - expected_completion_seconds - webhook_events - polling_hint description: Inline async ref - no activity_log row exists in this service. required: - total_rows - pending meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: string nullable: true description: >- The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: string nullable: true description: >- user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - operation - action - item - result - meta McpError: type: object properties: success: type: boolean enum: - false error: type: object properties: code: type: string enum: - validation_failed - nothing_to_update - not_found - relation_not_found - invalid_transition - limit_exceeded - payment_required - duplicate_rejected - conflict - delete_blocked - unauthorized - forbidden - rate_limited - internal_error - service_unavailable - not_implemented message: type: string recoverable: type: boolean suggestion: type: string field_errors: type: object additionalProperties: type: array items: type: object properties: rule: type: string message: type: string required: - rule - message blockers: type: array items: type: object properties: type: type: string description: >- Machine-readable blocker type (active_flow, pending_tasks, …). severity: type: string enum: - hard - soft description: >- hard = external action required; soft = acknowledge is enough. description: type: string entity_sid: type: string nullable: true count: type: integer resolution: type: string description: 'Hard: tool name to call. Soft: code for acknowledge[].' resolution_hint: type: string required: - type - severity - description - entity_sid - resolution - resolution_hint context: type: object additionalProperties: {} required: - code - message - recoverable meta: type: object properties: trace_id: type: string description: UUID v7; same 128-bit value as the X-Trace-Id header. span_id: type: string pattern: ^[0-9a-f]{16}$ description: 16 hex chars, root span of this request. timestamp: type: string description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. duration_ms: type: integer minimum: 0 description: Server-side wall clock. team_sid: type: string nullable: true description: >- The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends. actor_type: type: string nullable: true description: >- user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. required: - trace_id - span_id - timestamp - duration_ms required: - success - error responses: McpClientError: description: >- MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented. content: application/json: schema: $ref: '#/components/schemas/McpError' McpServerError: description: >- MCP error envelope with `error.code` internal_error or service_unavailable. content: application/json: schema: $ref: '#/components/schemas/McpError' securitySchemes: BearerJwt: type: http scheme: bearer bearerFormat: JWT description: >- Access token issued by gs.service.id. Its `access_identity` claim carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is authoritative. TeamSid: type: apiKey in: header name: Team-SID description: >- Team scope for tokens that do not carry one. Ignored when the token already names a team. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.