How to Link a Zendesk Organization to a Salesforce Account
Set the Zendesk org external_id equal to the Salesforce account id. If there is exactly one domain-based candidate with blank external_id, Gremlin prepares set_org_external_id as a safe action. If there is no candidate, you create the Zendesk org manually, then re-audit.
Published April 17, 2026 - Part of the Zendesk drift audit guide
Short answer
Use the CLI when the candidate is unique. Create manually when it is not.
- org_missing_external_id is auto-prepared as set_org_external_id when exactly one domain-based org candidate has a blank external_id.
- account_missing_zendesk_org is review-only. Gremlin does not create Zendesk organizations in v1.
- Dry-run first: g-gremlin zendesk drift apply --plan <fix_plan.json>.
- Live apply requires --apply and --confirm-plan-hash matching fix_plan.json.plan_hash.
- The canonical link is always Zendesk org external_id = sf_account_id.
When set_org_external_id is safe to apply
Four preconditions. All must hold, or the action does not get prepared.
Exactly one domain-based org candidate
The Salesforce account resolves to one and only one Zendesk org via normalized domain overlap. Multiple candidates stay review-only.
Target org external_id is blank
If the candidate org already carries a nonblank external_id, the issue becomes org_external_id_conflict and is review-only.
No other org already uses the intended id
Gremlin pre-checks every other Zendesk org. If the intended sf_account_id is in use elsewhere, the action is blocked to avoid creating a duplicate.
Account not blocked upstream
Accounts with duplicate external_ids or unresolved ambiguity never get a prepared set_org_external_id action.
Link a Zendesk org to a Salesforce account from the terminal
# 1. Audit the full surface
g-gremlin zendesk drift audit
# 2. Trace one account to see the candidate and preconditions
g-gremlin zendesk drift trace --sf-account-id 001ACME001
# 3. Dry-run the fix plan
g-gremlin zendesk drift apply \
--plan ./artifacts/zendesk_drift/20260417_221530Z_audit/fix_plan.json
# 4. Live apply (only the safe set_org_external_id and friends)
g-gremlin zendesk drift apply \
--plan ./artifacts/zendesk_drift/20260417_221530Z_audit/fix_plan.json \
--apply \
--confirm-plan-hash 8c5d4d4d4b0f1a... \
--action set_org_external_id--action is optional. It restricts the live apply to one action type for a narrower rollout, useful when ops wants to roll out org fixes before user fixes.
Resolution path
Run the audit
g-gremlin zendesk drift audit produces org_issues.csv and fix_plan.csv. Rows with issue_code = org_missing_external_id are auto-prepared as set_org_external_id when preconditions hold.
Trace the candidate
g-gremlin zendesk drift trace --sf-account-id <id> prints the domain evidence, the target org, and the preconditions Gremlin evaluated.
Dry-run apply
g-gremlin zendesk drift apply --plan <fix_plan.json>. Without --apply, Gremlin revalidates preconditions and writes a simulated apply_receipt.json.
Live apply with --confirm-plan-hash
Re-run with --apply --confirm-plan-hash <hash>. Gremlin sets the target org external_id to the Salesforce account id and writes the receipt.
Handle account_missing_zendesk_org manually
If Gremlin emits account_missing_zendesk_org, there is no unique domain candidate. Create the Zendesk org in Zendesk admin with external_id = sf_account_id, then re-audit.
FAQ
What is the canonical way to link a Zendesk organization to a Salesforce account?
Set the Zendesk org external_id equal to the Salesforce account id. This is the one match Gremlin treats as definitive. Domain-based matching is a secondary signal used only to identify candidate orgs when external_id is blank.
What does org_missing_external_id mean?
Gremlin found exactly one Zendesk org that matches a Salesforce account by normalized domain, and that org has a blank external_id. The fix is safe-to-apply via set_org_external_id because there is no ambiguity and no other org is claiming the intended id.
What does account_missing_zendesk_org mean?
A Salesforce account has no unique external_id match and no unique domain-resolved target org in Zendesk. The issue is review-only because Gremlin will not create organizations in Zendesk. Create the org manually (or via your sync mechanism) with external_id = sf_account_id, then re-audit.
Will set_org_external_id overwrite an existing Zendesk external_id?
No. The precondition requires the target org external_id to be blank. If the target has a nonblank external_id that conflicts with the expected Salesforce account, the issue becomes org_external_id_conflict and stays review-only.
How does Gremlin decide the domain-based candidate?
Domains are lowercased, stripped of protocol, path, query, port, and leading www., and deduplicated. Personal email domains like gmail.com, outlook.com, yahoo.com, icloud.com, hotmail.com, and protonmail.com are excluded. The candidate must be a unique exact match; fuzzy inference is never used.
What if my Salesforce CSV has an explicit zendesk_domain_override?
If present, zendesk_domain_override becomes the account’s effective domain set for matching and repair planning. This is the only supported v1 override. It is useful when the website field is messy and you want an operator-reviewed authoritative domain list.
Related Zendesk drift pages
Salesforce and Zendesk integration pillar
The audit-first integration contract: 12 issue codes, 4 safe actions, plan-hash-protected apply.
Open pageZendesk drift playbook
Operator execution log: Slack message, prompt, audit, review, dry-run, apply.
Open pageFix duplicate external_id in Zendesk
The critical blocker: what to do when two orgs share the same external_id.
Open pageZendesk domain collision between organizations
What to do when the expected domain belongs to another Zendesk org.
Open pageFix wrong default organization in Zendesk
The safe-to-apply fix for user_default_org_not_expected.
Open pageAudit Zendesk and Salesforce sync from the CLI
The focused CLI walkthrough for the drift audit workflow.
Open pageKeep the conversation going
These pages are meant to help operators solve real problems. If you want the next guide, grab the low-friction option. If you need the implementation, not just the guide, book time.
Get the next guide when it ships
I publish architecture guides grounded in real implementations. No generic AI filler.
Use your work email so I can keep the list useful and relevant.
Need the implementation, not just the guide?
Book a 15-minute working session with Mike right on his calendar. Tooling, consulting, or a mix of both is fine.
Open Mike's calendarIf you want me to come in with context, leave your email and a short note before the call.