For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Log inBook a demo
GuidesAPI Reference
GuidesAPI Reference
  • API Reference
      • GETList Bulk Syncs
      • POSTCreate Bulk Sync
      • GETGet Bulk Sync
      • PUTUpdate Bulk Sync
      • DELDelete Bulk Sync
      • POSTActivate Bulk Sync
      • POSTCancel Bulk Sync
      • POSTStart Bulk Sync Execution
      • GETGet Bulk Sync Status
      • GETGet Bulk Source
      • GETGet Bulk Destination
Logo
Log inBook a demo
API ReferenceBulk Sync

Create Bulk Sync

POST
https://app.polytomic.com/api/bulk/syncs
POST
/api/bulk/syncs
$curl -X POST https://app.polytomic.com/api/bulk/syncs \
>     -H "Authorization: Bearer <token>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "default_schedule": {
>    "frequency": "manual"
>  },
>  "destination_configuration": {
>    "schema": "my_schema"
>  },
>  "destination_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
>  "mode": "snapshot",
>  "name": "My Bulk Sync",
>  "source_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d"
>}'
1{
2  "data": {
3    "active": true,
4    "additional_schedules": [
5      {
6        "frequency": "weekly",
7        "created_at": "2023-04-25T12:00:00Z",
8        "created_by": {
9          "id": "12345678-1234-1234-1234-123456789012",
10          "name": "John Doe",
11          "type": "user"
12        },
13        "day_of_week": "monday",
14        "hour": "12",
15        "minute": "30",
16        "selective_mode": "nonincrementalFields",
17        "updated_at": "2023-04-25T12:00:00Z",
18        "updated_by": {
19          "id": "12345678-1234-1234-1234-123456789012",
20          "name": "John Doe",
21          "type": "user"
22        }
23      },
24      {
25        "frequency": "continuous",
26        "created_at": "2023-04-25T12:00:00Z",
27        "created_by": {
28          "id": "12345678-1234-1234-1234-123456789012",
29          "name": "John Doe",
30          "type": "user"
31        },
32        "selective_mode": "incrementalFields",
33        "updated_at": "2023-04-25T12:00:00Z",
34        "updated_by": {
35          "id": "12345678-1234-1234-1234-123456789012",
36          "name": "John Doe",
37          "type": "user"
38        }
39      }
40    ],
41    "automatically_add_new_fields": "all",
42    "automatically_add_new_objects": "all",
43    "concurrency_limit": 50,
44    "created_at": "2024-01-15T09:30:00Z",
45    "created_by": {
46      "id": "12345678-1234-1234-1234-123456789012",
47      "name": "John Doe",
48      "type": "user"
49    },
50    "data_cutoff_timestamp": "2023-04-25T12:00:00Z",
51    "default_schedule": {
52      "frequency": "manual",
53      "created_at": "2024-01-15T09:30:00Z",
54      "created_by": {
55        "id": "12345678-1234-1234-1234-123456789012",
56        "name": "John Doe",
57        "type": "user"
58      },
59      "day_of_month": "1",
60      "day_of_week": "monday",
61      "hour": "12",
62      "id": "248df4b7-aa70-47b8-a036-33ac447e668d",
63      "minute": "30",
64      "month": "1",
65      "updated_at": "2024-01-15T09:30:00Z",
66      "updated_by": {
67        "id": "12345678-1234-1234-1234-123456789012",
68        "name": "John Doe",
69        "type": "user"
70      }
71    },
72    "destination_configuration": {
73      "schema": "my_schema"
74    },
75    "destination_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
76    "disable_record_timestamps": false,
77    "id": "248df4b7-aa70-47b8-a036-33ac447e668d",
78    "mode": "snapshot",
79    "name": "My Bulk Sync",
80    "normalize_names": "enabled",
81    "organization_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
82    "policies": [
83      "248df4b7-aa70-47b8-a036-33ac447e668d"
84    ],
85    "resync_concurrency_limit": 10,
86    "source_configuration": {
87      "replication_slot": "slot"
88    },
89    "source_connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
90    "updated_at": "2024-01-15T09:30:00Z",
91    "updated_by": {
92      "id": "12345678-1234-1234-1234-123456789012",
93      "name": "John Doe",
94      "type": "user"
95    }
96  }
97}
Creates a new bulk sync. Bulk syncs are used for the ELT pattern (Extract, Load, and Transform), where you want to sync un-transformed data to your data warehouses, databases, or cloud storage buckets like S3. All of the functionality described in [the product documentation](https://docs.polytomic.com/docs/bulk-syncs) is configurable via the API. Sample code examples: - [Bulk sync (ELT) from Salesforce to S3](../../../guides/code-examples/bulk-sync-elt-from-salesforce-to-s-3) - [Bulk sync (ELT) from Salesforce to Snowflake](../../../guides/code-examples/bulk-sync-elt-from-salesforce-to-snowflake) - [Bulk sync (ELT) from HubSpot to PostgreSQL](../../../guides/code-examples/bulk-sync-elt-from-hub-spot-to-postgre-sql) ## Connection specific configuration The `destination_configuration` is integration-specific configuration for the selected bulk sync destination. This includes settings such as the output schema and is required when creating a new sync. The `source_configuration` is optional. It allows configuration for how Polytomic reads data from the source connection. This will not be available for integrations that do not support additional configuration. Consult the [connection configurations](../../../guides/configuring-your-connections/overview) to see configurations for particular integrations (for example, [here](../../../guides/configuring-your-connections/connections/postgre-sql#source-1) is the available source configuration for the PostgreSQL bulk sync source). ## Defaults and selection behavior If `schemas` is omitted, the sync is created with all available source schemas selected. Pass `schemas` explicitly if you want the initial sync to include only a subset of tables or objects. Schedule times are interpreted in UTC. When omitted, automatic discovery defaults are conservative: - `automatically_add_new_objects` defaults to not enabling newly discovered source objects automatically. - `automatically_add_new_fields` defaults to enabling newly discovered fields on already selected objects. - `normalize_names` defaults to enabled.
Was this page helpful?
Previous

Get Bulk Sync

Next

Creates a new bulk sync.

Bulk syncs are used for the ELT pattern (Extract, Load, and Transform), where you want to sync un-transformed data to your data warehouses, databases, or cloud storage buckets like S3.

All of the functionality described in the product documentation is configurable via the API.

Sample code examples:

  • Bulk sync (ELT) from Salesforce to S3
  • Bulk sync (ELT) from Salesforce to Snowflake
  • Bulk sync (ELT) from HubSpot to PostgreSQL

Connection specific configuration

The destination_configuration is integration-specific configuration for the selected bulk sync destination. This includes settings such as the output schema and is required when creating a new sync.

The source_configuration is optional. It allows configuration for how Polytomic reads data from the source connection. This will not be available for integrations that do not support additional configuration.

Consult the connection configurations to see configurations for particular integrations (for example, here is the available source configuration for the PostgreSQL bulk sync source).

Defaults and selection behavior

If schemas is omitted, the sync is created with all available source schemas selected. Pass schemas explicitly if you want the initial sync to include only a subset of tables or objects.

Schedule times are interpreted in UTC.

When omitted, automatic discovery defaults are conservative:

  • automatically_add_new_objects defaults to not enabling newly discovered source objects automatically.
  • automatically_add_new_fields defaults to enabling newly discovered fields on already selected objects.
  • normalize_names defaults to enabled.

Authentication

AuthorizationBearer
Bearer user API key
OR
AuthorizationBasic

Basic organization-scoped API key

Headers

X-Polytomic-VersionstringOptional

Request

This endpoint expects an object.
default_scheduleobjectRequired
destination_configurationmap from strings to anyRequired

Destination-specific bulk sync configuration (e.g. output schema name, file format). The accepted keys depend on the destination connection type.

destination_connection_idstringRequiredformat: "uuid"
Unique identifier of the connection rows are written to.
modeenumRequired
Allowed values:
namestringRequired

Human-readable name for the bulk sync.

source_connection_idstringRequiredformat: "uuid"
Unique identifier of the connection rows are read from.
activeboolean or nullOptional
Whether the sync is active. Inactive syncs do not run on their schedule but can still be triggered manually.
additional_scheduleslist of objects or nullOptional
Additional bulk sync schedules. Schedule times are interpreted in UTC.
automatically_add_new_fieldsenumOptional
Allowed values:
automatically_add_new_objectsenumOptional
Allowed values:
concurrency_limitinteger or nullOptional
Override the default concurrency limit for this sync.
data_cutoff_timestampdatetime or nullOptional
Global cutoff applied across schemas. Source records older than this timestamp are excluded from sync runs.
disable_record_timestampsboolean or nullOptionalDefaults to false
When true, Polytomic will not add its own timestamp columns to destination rows.
normalize_namesenumOptional
Allowed values:
organization_idstring or nullOptionalformat: "uuid"

Organization the sync is created in. Only used by partner callers; normal callers always create syncs in their own organization.

policieslist of strings or nullOptional
Identifiers of permissions policies applied to the bulk sync.
resync_concurrency_limitinteger or nullOptional
Override the default resync concurrency limit for this sync.
schemaslist of strings or objects or nullOptional

List of schemas to sync; if omitted, all schemas will be selected for syncing.

source_configurationmap from strings to any or nullOptional

Source-specific bulk sync configuration (e.g. replication slot name, sync lookback). The accepted keys depend on the source connection type.

Response

OK
dataobject

Errors

400
Bad Request Error
403
Forbidden Error
422
Unprocessable Entity Error
500
Internal Server Error