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

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 for failed runs. Go to Setup → Apex Jobs. A failed run appears as a Failed job named StatusPollFailureReporter, with the failure details (campaign and HTTP error) in its status column. UpdateLeadHandlerBatch rows 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).

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's campaign has no API key.	Paste the campaign API key from Aktify into Aktify Campaign API Key on the Campaign and make sure the campaign is Active. Adding the key syncs the campaign's unsynced leads automatically.
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.