Troubleshooting

Nothing is syncing

1. Check permission set assignment first. This is the most common cause, and it fails silently — no error is shown to the user. Confirm the lead's creator has the Aktify Managed Package Permissions permission set (see Installation & Setup). Remember that assignments are lost on uninstall/reinstall.
2. Check the sync attempts. Go to Setup → Apex Jobs. Rows with Job Type Future show each sync attempt and any error it hit.
3. "We couldn't access the credential(s)" in Apex Jobs. The org's credential access isn't activated yet. Open the Aktify app's config tab once — loading it grants you the package permission set, activates the credential, and schedules the status poll. If the failing user isn't you, assign them the permission set per step 1. (Manual credential equivalent: Setup → Named Credentials → External Credentials tab → Aktify API Auth → on the Anonymous principal, Edit → Save without entering anything.)

Leads added to a campaign aren't syncing

If you added leads to a campaign (from the campaign page, a list view, a report, or an import) and they show Api Key required or never sync:

1. Check the package version. Before 1.2.0 the package only reacted to the Aktify Campaign Id field on the Lead and ignored Campaign Members entirely, so leads added any other way never synced. Upgrade, then use Sync Campaign Members (step 4) to pick up the members you already added.
2. Check the campaign. It must be Active and have Aktify Campaign API Key set. Members added before the key existed are picked up when you save the key.
3. Check the lead's Aktify Campaign Id. If it names a different campaign, the lead is already in Aktify under that campaign and is deliberately not moved; one lead belongs to one Aktify campaign. If it's blank, continue.
4. Run Sync Campaign Members. In the Aktify app, open the Sync Campaign Members tab and click Sync Members on the campaign. The confirmation lists how many leads were queued and why any were skipped.
5. Contacts don't sync. Only Lead members are posted; Contact members are counted as skipped.

Fewer leads in Aktify than show as synced

Aktify Synced means Aktify accepted the lead for processing, not that it is already being worked:

• Leads in an Aged (non-real-time) Aktify campaign wait for that campaign's schedule before they appear in the flow. Ask Aktify to switch the campaign to Real Time if you need leads worked as they arrive.
• A draining campaign accepts leads but posts none of them. Aktify campaigns are live (posts new leads and engages them), draining (posts no new leads, but keeps working the leads it already has), or stopped (neither). Leads sent to a draining campaign are accepted, so Salesforce marks them Aktify Synced, but they are never worked. Ask Aktify which state the campaign is in if synced leads show no activity.
• Aktify may still reject a lead during processing — a phone number already in the campaign, an invalid or landline number, or a Do Not Contact match. Those rejections are not written back to the Salesforce lead.

Compare the numbers with Aktify support if the gap is larger than these explain.

Statuses aren't updating

If leads sync out but Aktify Lead Status and the activity counters never fill in:

1. Confirm the poll is scheduled. Go to Setup → Scheduled Jobs and look for Aktify Leads Status Update (sub-hourly cadences show several numbered entries). It's created automatically the first time an admin opens the Aktify config tab or saves a campaign API key; if it's missing, open the Aktify app's config tab once, or re-save the interval on its Status Sync Schedule card.
2. Check the last poll's issues. Open the Aktify Create Lead Config Setting tab. Below the Status Sync Schedule card, a warning box lists anything the most recent poll could not do, per campaign (an HTTP error, a campaign Aktify reports as not active, and so on). When the last poll was clean, the card says so and shows how far it has processed. The poll never raises errors or sends exception emails; this box is where its problems appear. (UpdateLeadHandlerBatch rows under Setup → Apex Jobs are the poll runs themselves.)
3. Check the campaign API key. The poll only queries Active campaigns that have Aktify Campaign API Key set — statuses stop updating if the key was cleared (for example by an uninstall/reinstall).
4. "Aktify reports this campaign is STOPPED". The campaign is Active in Salesforce, but on Aktify's side it is stopped: it neither posts new leads nor engages existing ones, so there are no statuses to fetch and there never will be while it stays stopped. Uncheck Active on the Salesforce campaign if it's finished, or ask Aktify to set it back to live. Other campaigns keep polling normally.

Upgrading from 1.1.0 or earlier

Earlier versions surfaced poll failures as a Failed StatusPollFailureReporter job in Apex Jobs, which also emailed the org's Apex exception recipients on every scheduled run. From 1.2.0 the poll records issues on the config tab instead and never throws.

Fields aren't visible

• Confirm the packaged fields were added to the page layout assigned to your users' profiles — most orgs have more than one Lead layout.
• If the layout is correct but the fields still don't show, hard-refresh the browser or log out and back in; Lightning caches layouts.

See Installation & Setup.

Sync failure reference

When a lead fails to sync, Aktify Sync Failed Reason on the lead holds the reason:

Message	Meaning	Fix
Api Key required	The lead has no Aktify Campaign Id, or the campaign it names has no API key.	If the lead should be in an Aktify campaign, add it to that campaign (as a Campaign Member, or by setting Aktify Campaign Id). If the campaign has no key yet, paste the key from Aktify into Aktify Campaign API Key and make sure the campaign is Active; saving the key syncs the campaign's unsynced leads and members automatically. Leads that are not meant for Aktify can be ignored.
API key is invalid or missing. Ensure the X-Api-Key header is present and correct.	Seen on versions before 1.2.0: the lead was created in bulk without an Aktify Campaign Id, so the package sent a request with no key. Despite the wording, no key was changed or lost.	Same fix as Api Key required. Upgrading to 1.2.0 replaces this message with Api Key required.
Valid two-character state or US postal code required	The lead has no valid geo signal.	Set State to a two-character code or full state name (CA / California), or set Zip/Postal Code to a valid US zip (12345 or 12345-6789). The sync retries automatically once the address is fixed.
Duplicate-lead response	The lead's phone number already exists in the Aktify campaign.	No action needed — Aktify is already working the lead.
400 : Missing required metadata fields: ['plan_tier']	The Aktify campaign requires the listed metadata key(s) and the lead was posted without them.	Add a mapping row for each listed key in the Aktify Metadata Mapping card for that Campaign (see Sending metadata with leads). Saving the mappings re-posts the campaign's leads that failed this way automatically; you can also re-sync them from the Sync Lead tab.
400 : Lead metadata is invalid...	A metadata value could not be sent as text.	This shouldn't occur with mappings created in the app; if it does, check the mapped Lead field's type and contact Aktify support with the message.

Metadata isn't reaching Aktify

If leads sync but Aktify reports the metadata is missing or wrong:

• Check the mapping is on the right Campaign. Mappings are per Campaign; a lead only carries the rows of the Campaign in its Aktify Campaign Id.
• Check the key name. It must match Aktify's key exactly, including case.
• Check what the field actually stores. Picklists send the API name, not the label. Use a formula field to translate values if needed.
• Blank field, no default. An empty string is sent, which Aktify accepts but renders as an empty spot in messages. Set a Default Value or populate the field.
• Changing a mapped field re-syncs only unsynced leads. Once a lead has synced, editing its mapped fields doesn't re-post it; Aktify rejects re-posts of the same phone number as duplicates in any case.

For anything not covered here, contact Aktify support with the lead's Aktify Sync Failed Reason value and the error text from Setup → Apex Jobs.