● all systems nominal
> docs/getting-started

Getting started with CleverSync

A pipeline moves records from one connection to another on a schedule. You add connections once, then build as many pipelines on top of them as your plan allows.

Connect Salesforce

Go to Connections → New → Salesforce. Choose Production or Sandbox, then pick how to sign in:

  • OAuth (recommended). Click Sign in with Salesforce and approve access. CleverSync stores a refresh token, so the connection keeps working when your password changes.
  • Username, password and security token. For integration users that can't use OAuth. Reset the security token from Settings → My Personal Information → Reset My Security Token in Salesforce; it's emailed to the user.

Use a dedicated integration user with read access to the objects you sync, and edit access to any object you load into. Click Test connection to confirm CleverSync can list your objects.

Connect HubSpot

Click Sign in with HubSpot and approve access, or paste a private app access token (Settings → Integrations → Private apps) with the crm.objects.*.read / .write and crm.schemas.*.read scopes for the objects you sync. Pipelines pick an object: contacts, companies, deals, tickets, products, line items, quotes, engagements, or a custom object.

  • Reading: every property is a column, typed from the property definition. Incremental runs use the last-modified date and leave records changed in the last minute for the next run, because HubSpot's search index lags writes. Deleted (archived) records can be removed from a database destination.
  • Writing: insert, update by record ID, or upsert on a unique property (contacts: email; any property marked unique on custom objects) or on the record ID. Rows go in batches of 100; a rejected batch is retried row by row so only bad rows land in the error file. Lookups and duplicate checks work against HubSpot too.

Connect MySQL

Add the host, port (usually 3306), database name, username and password. Then:

  1. Allow-list CleverSync's egress IP address in your firewall, security group or managed database settings. The address is listed in Settings.
  2. Grant the user SELECT on tables you read from, and CREATE, ALTER, INSERT, UPDATE on the database you write to so tables and columns can be created.
  3. Turn on Require TLS if your server supports it.

Connect PostgreSQL

Works with PostgreSQL 11 and later, Amazon RDS and Aurora PostgreSQL, Supabase and Neon. Add the host, port (usually 5432), database, schema (usually public), username and password. Then:

  1. Allow-list CleverSync's egress IP address (listed in Settings).
  2. Grant the user SELECT on tables you read from, and CREATE, INSERT, UPDATE on the schema you write to. To add columns to an existing table, the user must own it.
  3. Turn on Require TLS if your server supports it (managed services usually do).

Connect SQL Server

Works with SQL Server 2016 and later, Azure SQL Database and Azure SQL Managed Instance. Add the host (for Azure, yourserver.database.windows.net), port 1433, database, schema (usually dbo) and a SQL Server login. Then:

  1. Allow-list CleverSync's egress IP address (listed in Settings). On Azure SQL, add it under Networking → Firewall rules.
  2. Grant the login SELECT on tables you read from, and CREATE TABLE, ALTER, INSERT, UPDATE and DELETE on the schema you write to.
  3. Keep Encrypt connection on; Azure SQL requires it.

Text columns are created as NVARCHAR, so names and notes in any language are kept intact. Upserts use MERGE on the primary key you choose.

Connect MongoDB

Paste the connection string from Atlas (Connect → Drivers) or your own server, including the password, and name the database if it isn't in the string. Collections appear as tables. Allow CleverSync's egress IP address in Atlas Network Access.

  • Reading: documents are flattened — address.city becomes address_city, arrays become JSON text — and column types are inferred from a sample. The filter box takes a JSON query document such as {"status": "active"}. Incremental runs use a date field you pick.
  • Writing: rows are upserted on the key field you choose (a unique index is created for it) or appended without one. Dates are stored as real dates. A full refresh with replace loads a new collection and swaps it in.

Connect Snowflake

On Pro and above. Add your account identifier (e.g. myorg-myaccount), warehouse, database, schema and, optionally, a role. Sign in with a password or a key pair; for a key pair, register the public key with ALTER USER … SET RSA_PUBLIC_KEY = '…' and paste the private key (PEM).

  • The role needs USAGE on the warehouse, database and schema, SELECT for sources, and CREATE TABLE plus INSERT / UPDATE for destinations.
  • If your account has a network policy, allow CleverSync's egress IP address.

Connect Google BigQuery

On Pro and above. Enter the project ID and dataset, and paste a service-account key (JSON). Give the service account BigQuery Data Viewer and BigQuery Job User on the project to read, and BigQuery Data Editor to write. Set a location only for datasets outside the US and EU multi-regions.

  • Writes use one load job per run: rows are loaded into a staging table and merged into the target with MERGE on the pipeline's key, so a row sent again replaces the earlier one. There is no streaming buffer and no per-row insert cost. A full refresh with replace truncates the table and reloads it.
  • Sources read a table or a query; TIMESTAMP columns come through as UTC and nested STRUCT / ARRAY values as JSON text. Query sources are billed to the service account's project.

Connect Amazon Redshift

On Pro and above. Add the endpoint host, port (5439), database, schema, user and password; TLS is on by default. Redshift Serverless works the same way. Allow CleverSync's egress IP address in the cluster's security group, or reach a private cluster through an SSH tunnel.

  • Rows are staged in a session temp table and land in one commit when the run finishes: matching rows are deleted and re-inserted by the pipeline's key (Redshift doesn't enforce keys). A full refresh with replace empties the table and reloads it in the same transaction.
  • The user needs SELECT for sources, and CREATE, INSERT, UPDATE and DELETE on the schema for destinations. Text columns are created as varchar (up to 65,535 bytes) and JSON as SUPER.

Connect ClickHouse

On Pro and above. Add the host, port (8443 on ClickHouse Cloud, usually 8123 for a self-hosted server over plain HTTP), database, user and password. CleverSync talks to ClickHouse over its HTTP interface.

  • Destination tables are created as ReplacingMergeTree keyed on the primary key you choose, so a row sent again replaces the earlier one; reads use FINAL. Without a key, a MergeTree that appends. A full refresh with replace loads a new table and swaps it in with EXCHANGE TABLES.
  • The user needs SELECT for sources, and CREATE TABLE, INSERT and ALTER for destinations. If you use an IP allow-list, add CleverSync's egress IP address.

SSH tunnels

On Enterprise, MySQL, PostgreSQL, SQL Server, Redshift and ClickHouse connections can reach a database on a private network through your bastion host. Tick Connect through an SSH tunnel on the connection and enter the bastion host, SSH port and user, with a password or a private key.

  • The database host and port are as the bastion sees them, e.g. a private IP address.
  • The bastion needs AllowTcpForwarding yes and must accept SSH from CleverSync's egress IP address.
  • The bastion's host key is pinned on the first connection. If it changes, CleverSync refuses to connect until you click Re-trust on the connection.

Connect Google Sheets

A Google Sheets connection points at one spreadsheet; each pipeline picks a tab. Paste the spreadsheet link, then either click Sign in with Google, or paste a service-account key and share the spreadsheet with the service account's email (Viewer to read, Editor to write).

  • Reading: the first row holds the column names. The whole tab is read each run, since Sheets has no change tracking.
  • Writing: choose Replace the tab's contents or Add rows below. A tab that doesn't exist is created. Values are written as plain text and numbers, so nothing runs as a formula.
  • A spreadsheet holds up to 10 million cells; use a database for bigger syncs.

Connect Dropbox

Click Connect Dropbox and approve access. CleverSync can read CSV, Excel, JSON and Parquet files from, and write them to, any folder in that account. When you pick a Dropbox source you can read one file, the newest file in a folder, or every file that hasn't been processed yet.

Connect Amazon S3

Add the bucket, region, an optional prefix (folder) and an access key. The key needs s3:ListBucket on the bucket and s3:GetObject / s3:PutObject under the prefix. Pipelines read and write paths relative to the prefix.

S3-compatible stores such as Cloudflare R2, MinIO and Wasabi work too: enter their endpoint URL, and tick Path-style URLs for MinIO and most self-hosted stores.

Connect Google Cloud Storage

Add the bucket, an optional prefix (folder) and a service-account key: in Google Cloud, create a service account under IAM → Service accounts, add a JSON key and paste the file. Grant it Storage Object Viewer on the bucket to read and Storage Object Admin to write. Pipelines read and write paths relative to the prefix.

Connect Azure Blob Storage

Add the container and an optional prefix, then sign in with the storage account's connection string (Security + networking → Access keys), an account name and key, or a SAS token with Read and List (plus Write and Create for destinations). Data Lake Storage Gen2 accounts work the same way. Pipelines read and write paths relative to the prefix.

Connect SFTP

Add the host, port (usually 22), username and a base folder, then sign in with a password or a private key (with an optional passphrase). Pipelines read and write paths relative to the base folder. Allow-list CleverSync's egress IP address on the server. The server's host key is pinned on the first connection.

CSV, Excel, JSON & Parquet files

Under Files, upload a CSV, an Excel workbook, a JSON file or a Parquet file with a header row (column names). CSV files must be UTF-8; comma, semicolon and tab delimiters are detected automatically. Uploaded files can be the source of a pipeline, and every file a pipeline writes to file storage is listed there for download.

Excel sources (.xlsx, .xls, .ods, up to 100 MB) read the first visible sheet unless you name one; date cells come through as dates. For file destinations, pick CSV, Excel workbook, JSON array, newline-delimited JSON or Parquet — Excel output keeps numbers and dates as real Excel values and moves on to a new sheet after 1,048,575 rows.

JSON sources (.json, .jsonl, .ndjson) hold one object per line or one array of objects (an object wrapping one array, such as { "records": [...] }, works too). Nested objects become parent_child columns and arrays become JSON text. Parquet files (up to 500 MB) are read whole; integers, floats, booleans, dates and timestamps keep their types, and Parquet output is written with one optional column per field.

Output file names can use {name}, {object}, {date}, {time} and {run}. For a custom date, give a format: Advance Report As of {date:YYYY-MMM-DD}.csv writes Advance Report As of 2026-Oct-26.csv (YYYY, YY, MMM, MM, M, DD, D, HH, mm, ss). Dates use UTC unless you set Time zone for dates in the name, for example America/New_York.

Create a pipeline

Setup runs one screen at a time. Use Next and Back, or click a step to jump back to it. When you edit a pipeline, you can save from any screen.

  1. Source — a Salesforce object, a database table or query, a Google Sheets tab, or a CSV, Excel, JSON or Parquet file. For Salesforce objects and database tables, Only read some fields reads just the fields you pick. For Salesforce, Related fields adds fields from looked-up records, such as RecordType.Name or Owner.Email (up to five lookups deep). They map like any other field and land in columns such as RecordType_Name.
  2. Destination — a MySQL, PostgreSQL, SQL Server, Snowflake, BigQuery, Redshift or ClickHouse table or a MongoDB collection (new or existing), a Salesforce or HubSpot object with an operation (insert, update, or upsert by an external ID field), a Google Sheets tab, or a CSV, Excel, JSON or Parquet file in Dropbox, S3, Google Cloud Storage, Azure Blob Storage, SFTP or file storage.
  3. Fields & mapping — tick the fields to write and check where each one goes (see below).
  4. Sync mode, filter & schedule — optionally only write rows that match a filter (see below).
  5. Alerts, then Review: name the pipeline, check the summary, and create it. Use Run now to test it.

For a new database table, CleverSync uses the Salesforce object name in lower case (e.g. opportunity, loan__c) with Id as the primary key. You can rename it before the first run.

Schedules

  • Manual — only runs when you click Run now.
  • Interval — every N minutes, hours or days. The fastest interval depends on your plan, down to every minute on Business.
  • Cron — a standard 5-field expression with a time zone, e.g. 0 6 * * 1-5 for 6:00 every weekday. The next run times are previewed as you type.
  • After another pipeline (Business and above) — runs when the pipelines you pick succeed, or succeed with some rejected rows. Use it to load data into Salesforce only after the export it depends on has finished.

A pipeline never overlaps itself: if a run is still going when the next one is due, the next one waits.

Mapping & transforms

Fields are matched by name, ignoring case, spaces, underscores and the __c suffix, so a CSV column Annual Revenue maps to AnnualRevenue. You can change any target, untick fields you don't want, and add a transform:

TransformWhat it does
trimRemoves leading and trailing whitespace.
upper / lowerConverts text to upper or lower case.
null if emptyTurns empty strings into NULL, so they don't overwrite values with blanks.
constantIgnores the source and writes a fixed value, e.g. LeadSource = "Partner file".
dateParses a date or date-time in a format you choose (e.g. MM/DD/YYYY) and writes ISO 8601.

Every source field is listed whether or not it matched, so you can see at a glance what lands where. Each row shows whether the target is an existing field or column, a new column CleverSync will create, or still needs a choice. When the names differ on each side, pick the target from the list or type a new column name. Use the search box and the Not selected and Check filters on wide objects. For database and file destinations, Mirror the source schema copies every field as-is and picks up fields added later. Untick a field or rename one to switch to a custom mapping. When you write to a table that already exists, tick Only use columns that already exist. Fields are then matched only to the table's columns, and nothing is added to the table. For Salesforce and database sources, Only query the mapped fields reads just the fields you mapped, so fields the destination doesn't have are never pulled. It's on by default when you write to Salesforce or limit writes to existing columns.

For files, spreadsheets and new tables, the Column order panel under the mapping sets the order of the output columns: drag rows or use the arrows, sort A–Z, or go back to the source's order. Fields you tick later slot in by their source position without disturbing your order.

Lookups, duplicates & data quality

When the destination is Salesforce, three extra tools run on each row before anything is written.

Look up Salesforce Ids. A CSV says Acme Corp; the Contact's AccountId needs the Account's Id. Set the transform on that field to look up Salesforce Id, choose the object and the field to match on (Name, Email, an external code…). CleverSync queries each distinct value once per run and writes the Id. Rows with no match are rejected (or written blank, your choice); rows that match more than one record are rejected as ambiguous. Fuzzy matching ignores case, punctuation, a leading "The" and suffixes like Inc, LLC and Corp, so ACME Corporation, Inc. finds Acme Corp.

Check for duplicates. Pick up to four mapped fields that identify a record — usually Email, or first name + last name + company. Before each batch is written, CleverSync looks for existing records with the same values and either skips the row or updates the existing record with it. Rows that repeat an earlier row in the same run are skipped too. Skipped rows appear in the run's error file with the matching record's Id, but they aren't counted as failures and don't trigger alerts. Fuzzy matching uses Salesforce search, which can lag a few seconds behind records created moments ago.

Data-quality rules. Require a field, check that it's a valid email, phone number or URL, matches a pattern, is within a length or number range, is one of a list of values, or is a date in the past or future. A failing row is rejected with the reason in the error file, or the offending field is blanked and the row written anyway. Blank values pass every check except required.

Org backups & restore

Backups keeps a copy of every record in a Salesforce org, without you mapping anything. Pick the org, a time of day, and optionally which objects to include or skip; the first run copies everything, and each run after that pulls only the records that changed since the last one, plus any that were deleted. History, Share, Feed and system objects are skipped automatically. Backups appear with your pipelines, so pausing, run history and alerts work the same way.

Every version of every record is kept, so you can open a record from the backup page (search by Id or name), walk through its versions, and see a field-by-field diff of what changed between any two. A deletion shows up as its own entry in the history.

Restore writes a chosen version back to Salesforce: either every field, or only the fields that changed in that version. If the record still exists it is updated; if it was deleted it is created again with a new Id (Salesforce doesn't allow re-using the old one). Read-only and system fields are skipped and listed afterwards. Restores need the editor role and are written to the audit log.

Row filters

Under Sync mode, filter & schedule, tick Only sync rows that match a filter to choose which rows get written or updated. Add conditions on any source field (equals, contains, is one of, greater than, is blank, in the last N days, and more). Combine them with all (AND), any (OR), or custom logic such as 1 AND (2 OR 3). Numbers and dates compare as numbers and dates, and text is case-insensitive. Filters work with every source. For large Salesforce objects, the SOQL filter on the source is faster, because it runs inside Salesforce.

Column types

When CleverSync creates or extends a database table from a Salesforce object, it uses these column types:

Salesforce typeMySQLPostgreSQLSQL ServerSnowflake
id, reference (lookup / master-detail)VARCHAR(18)varchar(18)varchar(18)VARCHAR(18)
string, email, phone, url, picklist, short textareaVARCHAR(length), TEXT above 255varchar(length)nvarchar(length)VARCHAR
textarea over 1,000 chars, multipicklist (values separated by ;)TEXT, MEDIUMTEXT above 4,000textnvarchar(max)VARCHAR
boolean (checkbox)TINYINT(1)booleanbitBOOLEAN
intINTintegerintNUMBER(38,0)
longBIGINTbigintbigintNUMBER(38,0)
double, currency, percentDECIMAL(p,s)numeric(p,s)decimal(p,s)NUMBER(p,s)
dateDATEdatedateDATE
datetime (UTC)DATETIME(3)timestamptz(3)datetime2(3)TIMESTAMP_TZ(3)
timeTIME(3)time(3)time(3)TIME(3)

Compound fields (Address, Geolocation) are synced as their individual component fields, e.g. BillingCity. New Salesforce fields become new columns on the next run; columns are never dropped.

Incremental sync & deletes

The first run of an incremental pipeline loads everything. After that, each run only fetches records whose SystemModstamp is newer than the last one seen, and upserts them by Id. Choose Full mode to reload everything on every run.

Turn on Include deleted records to also pick up records in the Salesforce recycle bin. They arrive with IsDeleted = 1 instead of being removed from your table, so history is kept.

To remove them instead, turn on Delete rows removed in Salesforce (Business and above). Each run checks the last 30 days of Salesforce deletes and deletes the matching rows from a database destination whose primary key is Id.

For database sources, choose a column such as updated_at as the incremental cursor.

Alerts & error files

Each pipeline can notify one or more channels:

  • Email — to any addresses you list.
  • Slack — paste an incoming-webhook URL for the channel.
  • Webhook — a JSON POST with the pipeline, run status, counts and error to any HTTPS URL.

Choose when to send: on failure, when some rows were rejected, on every success, and when a pipeline recovers. To avoid noise from a flaky source, you can alert only after a number of failures in a row.

When rows are rejected, the run is marked partial and the rejected rows are saved as a CSV with an error column. Download it from the run's page, fix the data, and load it again.

Team, roles & audit log

Invite teammates under Settings → Team. Starter has one seat and Pro has 3; Business and Enterprise are unlimited and add roles:

  • Viewer — sees connections, pipelines and runs, but can't change them.
  • Editor — creates and edits connections and pipelines, and runs them.
  • Admin — also manages members, billing, API keys and single sign-on.

Without roles, every member is an editor. On Business and above, the Audit log records who changed what and when, filterable by person and action.

Single sign-on

On Enterprise, admins can connect Okta, Microsoft Entra ID, Google Workspace or any OpenID Connect or SAML 2.0 identity provider under Settings → Single sign-on.

  1. OIDC: enter the issuer URL, client ID and secret, and add the redirect URI shown to your identity provider. SAML: copy the entity ID and ACS URL into your identity provider, then paste its metadata XML.
  2. List your email domains and verify each with a DNS TXT record (cleversync-verification=…).
  3. Click Test sign-in to check the setup before your team relies on it.

Optionally create members automatically on their first sign-in with a default role, and Require SSO so members can't use passwords. The workspace owner keeps password access as a break-glass account.

REST API

On Business and Enterprise you can list pipelines, trigger runs, check their status and pause pipelines from your own scheduler, CI or scripts. Create a key under Settings → API keys (workspace admins). The key is shown once; store it in a secret manager. Revoking a key stops it working immediately.

Send the key as a bearer token to https://cleversync.ai/api/v1. Requests and responses are JSON; errors look like { "error": "…" } with a 4xx/5xx status. API calls act as an editor and show up in the audit log as api:<key name>.

curl https://cleversync.ai/api/v1/pipelines \
  -H "Authorization: Bearer cs_live_…"
EndpointWhat it does
GET /pipelinesList pipelines with their source, destination, schedule, next run and last status.
GET /pipelines/:idOne pipeline.
PATCH /pipelines/:idPause or resume: { "enabled": false }. Other fields are edited in the app.
POST /pipelines/:id/runsQueue a run now. Optional body { "fullRefresh": true }. Returns 202 with the run id.
GET /pipelines/:id/runs?limit=20Recent runs, newest first (limit up to 200).
GET /runs/:id?log=50Run status, row counts, error, timestamps and the last log lines (up to 500).
POST /runs/:id/cancelCancel a queued or running run.
GET /connectionsConnections and their status. Credentials are never returned.

Trigger a run and wait for it

curl -X POST https://cleversync.ai/api/v1/pipelines/$PIPELINE_ID/runs \
  -H "Authorization: Bearer $CLEVERSYNC_KEY" -H "Content-Type: application/json" \
  -d '{"fullRefresh": false}'
# 202 {"run":{"id":"8c1f…","status":"queued"}}

curl https://cleversync.ai/api/v1/runs/8c1f… -H "Authorization: Bearer $CLEVERSYNC_KEY"
# {"run":{"status":"succeeded","rows_read":1200,"rows_written":1200,"rows_failed":0,"error":null,"log":[…]}}

Run status is one of queued, running, succeeded, partial, failed or canceled. Triggering a pipeline that already has a run queued or in progress returns 409.

Pause or resume a pipeline

curl -X PATCH https://cleversync.ai/api/v1/pipelines/$PIPELINE_ID \
  -H "Authorization: Bearer $CLEVERSYNC_KEY" -H "Content-Type: application/json" \
  -d '{"enabled": false}'

Limits

Each key can make 60 requests a minute on Business and 600 on Enterprise. Above that you get 429 with a Retry-After header in seconds. A missing, malformed or revoked key returns 401; a workspace whose plan no longer includes the API returns 402.

Ready to try it?

Start a free trial and connect your first org.

Start free trial