Import data source

curl --request POST \
  --url https://beta.getsales.io/playtables/v1/api/data-sources/{sid}/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Team-SID: <api-key>' \
  --data '
{
  "field_mapping": [
    {
      "source": "<string>",
      "target": "<string>",
      "name": "<string>"
    }
  ],
  "add_tags_to_duplicate": true,
  "qualify": {
    "on": true,
    "criterion": "<string>"
  }
}
'

import requests

url = "https://beta.getsales.io/playtables/v1/api/data-sources/{sid}/import"

payload = {
    "field_mapping": [
        {
            "source": "<string>",
            "target": "<string>",
            "name": "<string>"
        }
    ],
    "add_tags_to_duplicate": True,
    "qualify": {
        "on": True,
        "criterion": "<string>"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Team-SID": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Team-SID': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    field_mapping: [{source: '<string>', target: '<string>', name: '<string>'}],
    add_tags_to_duplicate: true,
    qualify: {on: true, criterion: '<string>'}
  })
};

fetch('https://beta.getsales.io/playtables/v1/api/data-sources/{sid}/import', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://beta.getsales.io/playtables/v1/api/data-sources/{sid}/import",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'field_mapping' => [
        [
                'source' => '<string>',
                'target' => '<string>',
                'name' => '<string>'
        ]
    ],
    'add_tags_to_duplicate' => true,
    'qualify' => [
        'on' => true,
        'criterion' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Team-SID: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://beta.getsales.io/playtables/v1/api/data-sources/{sid}/import"

	payload := strings.NewReader("{\n  \"field_mapping\": [\n    {\n      \"source\": \"<string>\",\n      \"target\": \"<string>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"add_tags_to_duplicate\": true,\n  \"qualify\": {\n    \"on\": true,\n    \"criterion\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Team-SID", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://beta.getsales.io/playtables/v1/api/data-sources/{sid}/import")
  .header("Authorization", "Bearer <token>")
  .header("Team-SID", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"field_mapping\": [\n    {\n      \"source\": \"<string>\",\n      \"target\": \"<string>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"add_tags_to_duplicate\": true,\n  \"qualify\": {\n    \"on\": true,\n    \"criterion\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://beta.getsales.io/playtables/v1/api/data-sources/{sid}/import")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Team-SID"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"field_mapping\": [\n    {\n      \"source\": \"<string>\",\n      \"target\": \"<string>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"add_tags_to_duplicate\": true,\n  \"qualify\": {\n    \"on\": true,\n    \"criterion\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "operation": "action",
  "action": "<string>",
  "item": {
    "sid": "<string>",
    "team_sid": "<string>",
    "playtable_sid": "<string>",
    "name": "<string>",
    "type": "ai_search",
    "object_type": "people",
    "sender_profile_sid": "<string>",
    "ingest_key": "<string>",
    "payload": {
      "platform": "linkedin",
      "surface": "search",
      "repeat": "hourly",
      "mode": "create",
      "target": "post",
      "window": {
        "days": 7
      },
      "relevance": {
        "prompt": "<string>"
      },
      "collect": {
        "reactions": true,
        "comments": true,
        "reposts": true
      },
      "posts": [
        {
          "urn": "<string>",
          "title": "<string>",
          "published_at": "<string>",
          "verdict": "match",
          "verdict_reason": "<string>"
        }
      ]
    },
    "field_mapping": [
      {
        "source": "<string>",
        "target_kind": "people_attribute",
        "target": "<string>",
        "name": "<string>"
      }
    ],
    "tag_sids": [
      "<string>"
    ],
    "qualify": {
      "on": true,
      "criterion": "<string>"
    },
    "on_duplicate": "skip",
    "add_tags_to_duplicate": true,
    "status": "draft",
    "status_reason": "<string>",
    "next_collect_at": "<string>",
    "created_by": {
      "actor_type": "user",
      "actor_sid": "<string>",
      "team_sid": "<string>",
      "permissions": {},
      "actor_name": "<string>",
      "oauth_client_sid": "<string>",
      "reason": "<string>",
      "cluster_id": 123,
      "trace_id": "<string>"
    },
    "deleted_by": {
      "actor_type": "user",
      "actor_sid": "<string>",
      "team_sid": "<string>",
      "permissions": {},
      "actor_name": "<string>",
      "oauth_client_sid": "<string>",
      "reason": "<string>",
      "cluster_id": 123,
      "trace_id": "<string>"
    },
    "created_at": "<string>",
    "updated_at": "<string>",
    "deleted_at": "<string>"
  },
  "result": {
    "total_rows": 1,
    "pending": {
      "expected_completion_seconds": 1,
      "webhook_events": [
        "data-sources.completed"
      ],
      "polling_hint": "<string>"
    }
  },
  "meta": {
    "trace_id": "<string>",
    "span_id": "<string>",
    "timestamp": "<string>",
    "duration_ms": 1,
    "team_sid": "<string>",
    "actor_type": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "<string>",
    "recoverable": true,
    "suggestion": "<string>",
    "field_errors": {},
    "blockers": [
      {
        "type": "<string>",
        "severity": "hard",
        "description": "<string>",
        "entity_sid": "<string>",
        "resolution": "<string>",
        "resolution_hint": "<string>",
        "count": 123
      }
    ],
    "context": {}
  },
  "meta": {
    "trace_id": "<string>",
    "span_id": "<string>",
    "timestamp": "<string>",
    "duration_ms": 1,
    "team_sid": "<string>",
    "actor_type": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "<string>",
    "recoverable": true,
    "suggestion": "<string>",
    "field_errors": {},
    "blockers": [
      {
        "type": "<string>",
        "severity": "hard",
        "description": "<string>",
        "entity_sid": "<string>",
        "resolution": "<string>",
        "resolution_hint": "<string>",
        "count": 123
      }
    ],
    "context": {}
  },
  "meta": {
    "trace_id": "<string>",
    "span_id": "<string>",
    "timestamp": "<string>",
    "duration_ms": 1,
    "team_sid": "<string>",
    "actor_type": "<string>"
  }
}

data_sources

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.

POST

api

data-sources

{sid}

import

Import data source

curl --request POST \
  --url https://beta.getsales.io/playtables/v1/api/data-sources/{sid}/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Team-SID: <api-key>' \
  --data '
{
  "field_mapping": [
    {
      "source": "<string>",
      "target": "<string>",
      "name": "<string>"
    }
  ],
  "add_tags_to_duplicate": true,
  "qualify": {
    "on": true,
    "criterion": "<string>"
  }
}
'

import requests

url = "https://beta.getsales.io/playtables/v1/api/data-sources/{sid}/import"

payload = {
    "field_mapping": [
        {
            "source": "<string>",
            "target": "<string>",
            "name": "<string>"
        }
    ],
    "add_tags_to_duplicate": True,
    "qualify": {
        "on": True,
        "criterion": "<string>"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Team-SID": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Team-SID': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    field_mapping: [{source: '<string>', target: '<string>', name: '<string>'}],
    add_tags_to_duplicate: true,
    qualify: {on: true, criterion: '<string>'}
  })
};

fetch('https://beta.getsales.io/playtables/v1/api/data-sources/{sid}/import', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://beta.getsales.io/playtables/v1/api/data-sources/{sid}/import",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'field_mapping' => [
        [
                'source' => '<string>',
                'target' => '<string>',
                'name' => '<string>'
        ]
    ],
    'add_tags_to_duplicate' => true,
    'qualify' => [
        'on' => true,
        'criterion' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Team-SID: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://beta.getsales.io/playtables/v1/api/data-sources/{sid}/import"

	payload := strings.NewReader("{\n  \"field_mapping\": [\n    {\n      \"source\": \"<string>\",\n      \"target\": \"<string>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"add_tags_to_duplicate\": true,\n  \"qualify\": {\n    \"on\": true,\n    \"criterion\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Team-SID", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://beta.getsales.io/playtables/v1/api/data-sources/{sid}/import")
  .header("Authorization", "Bearer <token>")
  .header("Team-SID", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"field_mapping\": [\n    {\n      \"source\": \"<string>\",\n      \"target\": \"<string>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"add_tags_to_duplicate\": true,\n  \"qualify\": {\n    \"on\": true,\n    \"criterion\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://beta.getsales.io/playtables/v1/api/data-sources/{sid}/import")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Team-SID"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"field_mapping\": [\n    {\n      \"source\": \"<string>\",\n      \"target\": \"<string>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"add_tags_to_duplicate\": true,\n  \"qualify\": {\n    \"on\": true,\n    \"criterion\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "operation": "action",
  "action": "<string>",
  "item": {
    "sid": "<string>",
    "team_sid": "<string>",
    "playtable_sid": "<string>",
    "name": "<string>",
    "type": "ai_search",
    "object_type": "people",
    "sender_profile_sid": "<string>",
    "ingest_key": "<string>",
    "payload": {
      "platform": "linkedin",
      "surface": "search",
      "repeat": "hourly",
      "mode": "create",
      "target": "post",
      "window": {
        "days": 7
      },
      "relevance": {
        "prompt": "<string>"
      },
      "collect": {
        "reactions": true,
        "comments": true,
        "reposts": true
      },
      "posts": [
        {
          "urn": "<string>",
          "title": "<string>",
          "published_at": "<string>",
          "verdict": "match",
          "verdict_reason": "<string>"
        }
      ]
    },
    "field_mapping": [
      {
        "source": "<string>",
        "target_kind": "people_attribute",
        "target": "<string>",
        "name": "<string>"
      }
    ],
    "tag_sids": [
      "<string>"
    ],
    "qualify": {
      "on": true,
      "criterion": "<string>"
    },
    "on_duplicate": "skip",
    "add_tags_to_duplicate": true,
    "status": "draft",
    "status_reason": "<string>",
    "next_collect_at": "<string>",
    "created_by": {
      "actor_type": "user",
      "actor_sid": "<string>",
      "team_sid": "<string>",
      "permissions": {},
      "actor_name": "<string>",
      "oauth_client_sid": "<string>",
      "reason": "<string>",
      "cluster_id": 123,
      "trace_id": "<string>"
    },
    "deleted_by": {
      "actor_type": "user",
      "actor_sid": "<string>",
      "team_sid": "<string>",
      "permissions": {},
      "actor_name": "<string>",
      "oauth_client_sid": "<string>",
      "reason": "<string>",
      "cluster_id": 123,
      "trace_id": "<string>"
    },
    "created_at": "<string>",
    "updated_at": "<string>",
    "deleted_at": "<string>"
  },
  "result": {
    "total_rows": 1,
    "pending": {
      "expected_completion_seconds": 1,
      "webhook_events": [
        "data-sources.completed"
      ],
      "polling_hint": "<string>"
    }
  },
  "meta": {
    "trace_id": "<string>",
    "span_id": "<string>",
    "timestamp": "<string>",
    "duration_ms": 1,
    "team_sid": "<string>",
    "actor_type": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "<string>",
    "recoverable": true,
    "suggestion": "<string>",
    "field_errors": {},
    "blockers": [
      {
        "type": "<string>",
        "severity": "hard",
        "description": "<string>",
        "entity_sid": "<string>",
        "resolution": "<string>",
        "resolution_hint": "<string>",
        "count": 123
      }
    ],
    "context": {}
  },
  "meta": {
    "trace_id": "<string>",
    "span_id": "<string>",
    "timestamp": "<string>",
    "duration_ms": 1,
    "team_sid": "<string>",
    "actor_type": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "<string>",
    "recoverable": true,
    "suggestion": "<string>",
    "field_errors": {},
    "blockers": [
      {
        "type": "<string>",
        "severity": "hard",
        "description": "<string>",
        "entity_sid": "<string>",
        "resolution": "<string>",
        "resolution_hint": "<string>",
        "count": 123
      }
    ],
    "context": {}
  },
  "meta": {
    "trace_id": "<string>",
    "span_id": "<string>",
    "timestamp": "<string>",
    "duration_ms": 1,
    "team_sid": "<string>",
    "actor_type": "<string>"
  }
}

Authorizations

Authorization

string

header

required

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.

Team-SID

string

header

required

Team scope for tokens that do not carry one. Ignored when the token already names a team.

Path Parameters

sid

string

required

The draft source (ds_sc_…) - must be status=draft, type=csv; anything else → 409 invalid_transition or 422.

Required string length: 18

Pattern: ^ds_sc_

Body

application/json

Request body of import_data_source.

field_mapping

object[]

required

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.

Show child attributes

object_type

enum<string>

Override what the rows become: people | company. Absent = what the upload said.

Available options:

people,

company

mode

enum<string>

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.

Available options:

create,

update

match

object

Required when the resulting mode is update, prohibited when it is create.

Show child attributes

on_duplicate

enum<string>

Override before start; default = the draft's stored policy.

Available options:

skip,

move

add_tags_to_duplicate

boolean

Override before start: merge tag_sids onto matched duplicates; default = the draft's stored policy.

qualify

object | null

The last word on the gate too: the block to run, null to switch it off, absent = what the upload said.

Show child attributes

Response

action success envelope.

success

enum<boolean>

required

Available options:

true

operation

enum<string>

required

Available options:

action

action

string

required

kebab-case verb; matches the route segment.

item

object | null

required

Show child attributes

result

object

required

Show child attributes

Overview

Playtables API

Unibox API

Signals API

Integrations API

ID and Teams API

Import data source

Authorizations

Path Parameters

Body

Response