How Lead Sync Works

When a lead syncs

A lead is sent to Aktify automatically when any of the following happens:

• A lead is created with Aktify Campaign Id set.
• An existing unsynced lead's Aktify Campaign Id is set or changed.
• An existing unsynced lead's State or Zip/Postal Code is corrected.
• An existing unsynced lead's value changes in any field that is mapped to metadata for its campaign.
• An API key is added to (or activated on) an Active campaign.

Adding an API key backfills the whole campaign

The last trigger applies to all of the campaign's unsynced leads at once: pasting a key into an Active campaign immediately posts every lead already assigned to it. Make sure the campaign's leads are ready to be contacted before you add the key.

What a lead needs to qualify

Each lead must have:

• A valid US phone number.
• At least one valid geo signal:
  • A two-character state code or full state name in State (e.g. CA or California), or
  • A valid US zip code in Zip/Postal Code (12345 or 12345-6789).

Leads with neither geo signal are not sent — Aktify Sync Failed Reason reads Valid two-character state or US postal code required. Fixing the State or Zip/Postal Code retries the sync automatically.

Sync results

• Success: Aktify Synced is checked on the lead.
• Failure: Aktify Sync Failed Reason holds the reason. Common examples:
  • Api Key required — the lead's campaign has no API key set.
  • A duplicate-lead response — the phone number already exists in the Aktify campaign.

See the Troubleshooting page for the full reference.

Sending metadata with leads

Aktify campaigns can carry metadata on each lead: named values that Aktify uses to personalize messaging or route the conversation. A campaign may require certain keys — Aktify tells you which when they provide the campaign's API key.

Metadata mappings are configured per Campaign, in the Aktify Metadata Mapping card on the Aktify Create Lead Config Setting tab (or on the Campaign record, if the component has been added to its page). Each row is one key:

Column	Meaning
Metadata Key	The key name exactly as Aktify configured it. Letters, digits, underscores, and hyphens only; each key appears once per campaign.
Lead Field	The Lead field whose value is sent. Any Lead field can be chosen, standard or custom. Leave it as No Lead field to send only the default value.
Default Value	Sent when the Lead field is blank, or always when no Lead field is chosen.

How the value is chosen

For each row, the value sent is:

1. The Lead field's value, if it isn't blank;
2. otherwise the Default Value, if set;
3. otherwise an empty string.

Every value is sent as text. Numbers, checkboxes, and dates are converted to their text form, and picklists send the stored API name, not the display label. If Aktify expects a different value than your field holds (for example your Plan picklist stores T3 but the campaign expects premium), create a formula field on Lead that returns the expected value and map that instead — the package does not translate values.

Campaigns with no mapping rows send no metadata at all, which is fine for campaigns that don't use it.

Saving mappings also re-posts any of the campaign's leads that Aktify previously rejected for missing metadata, so a campaign that was connected before its mappings were configured recovers on its own.

Required keys must be present, not just non-empty

Aktify checks that each required key is present on the lead. An empty string satisfies the check, but it produces an empty spot in any message that uses the key — so give required keys a sensible Default Value or make sure the mapped field is always populated.

Example

A campaign's outreach mentions the plan each lead asked about, so it requires a plan_tier key. Your Lead object has a formula field Aktify Plan Tier that returns basic, plus, or premium from your existing Plan picklist. The mapping row is:

Metadata Key	Lead Field	Default Value
plan_tier	Aktify Plan Tier	basic

A lead whose Plan resolves to premium is posted with plan_tier = premium; a lead with no Plan is posted with plan_tier = basic.

Manual re-sync

The Sync Lead tab in the Aktify app lists leads that haven't synced. Select the leads you want and click Sync with Aktify.

To re-send a lead that already synced, uncheck Aktify Synced on the lead first, then sync it again.

Status sync-back (Aktify → Salesforce)

A scheduled job polls Aktify and updates each synced lead's Aktify Lead Status plus the activity counters (Aktify Calls Placed, Aktify Calls Received, Aktify Messages Sent, Aktify Messages Received).

No dedicated setup is required. Polling activates automatically — with an hourly default — the first time an admin opens the Aktify app's config tab or saves a campaign API key, both of which happen during normal setup.

Changing the polling cadence

On the Aktify Create Lead Config Setting tab in the Aktify app, the Status Sync Schedule card lets an admin pick the interval — Hourly (every 1–23 hours), Daily, Every 15 Minutes, or Every 30 Minutes. Saving replaces the existing scheduled job with the new cadence.

The same card's Sync Statuses Now button runs one poll immediately — useful for testing or when you don't want to wait for the next scheduled run.

How it stays reliable

• The poll tracks how far it has successfully processed (Last Job Run Time on the config record). A failed or interrupted run resumes from where it stopped instead of skipping that time window.
• Very busy windows (more than 1,000 status changes) are fetched in smaller time slices automatically.
• If a run has errors, it appears as a Failed job named StatusPollFailureReporter under Setup → Apex Jobs, with the failure details in its status — that is the first place to look if statuses stop updating.