Getting started with CleverSync

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 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 Dropbox

Click Connect Dropbox and approve access. CleverSync can read CSV files from and write CSV files 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.

Upload CSV files

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

Create a pipeline

1. Source — a Salesforce object, a MySQL table or query, or a CSV file.
2. Destination — a MySQL table (new or existing), a Salesforce object with an operation (insert, update, or upsert by an external ID field), or a CSV file in Dropbox or file storage.
3. Mapping — review the auto-matched fields (see below).
4. Schedule and Alerts, then save. Use Run now to test it.

For a new MySQL 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.

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:

Field types in MySQL

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

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. For MySQL 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.

REST API

On the Business plan 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_…"

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. 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.