Autotask integration
Connect Gabriel to Autotask (Datto PSA) so your sales team and your service desk work from the same customer list. The integration works in two directions:
- From Autotask to Gabriel: an admin imports companies, their contacts and their addresses whenever they choose. You can import as often as you like, and records you already have are skipped, so nothing is copied twice.
- From Gabriel to Autotask: you push companies, contacts and opportunities to Autotask. With auto-sync on, later edits to linked records in Gabriel update Autotask too.
Edits made in Autotask after an import don’t flow back to Gabriel on their own.
An admin can set the integration up themselves under Settings > Integrations > PSA Integration, including during a trial. Setting it up and importing need the Manage organization settings permission. Once it’s connected, anyone who can edit a company or opportunity can push it.
Before you start
Section titled “Before you start”In Autotask, go to Admin > Resources > API Integration Users, create a user, note its username (it ends in @yourdomain.autotask.net) and generate a secret key. Give it a security level with the permissions below. You don’t need a zone or tracking code.
Permissions the API user needs
Section titled “Permissions the API user needs”Autotask checks every request Gabriel makes against the API user’s security level, not your own. The built-in API User (system) security level already covers everything below. If you give the API user a custom security level, make sure it includes:
| Autotask object | Access | What Gabriel uses it for |
|---|---|---|
| Companies | View, Add, Edit | Testing the connection, importing companies, checking for duplicates, pushing companies, and reading company types and industries |
| Company locations | View | Importing addresses with Import locations |
| Contacts | View, Add, Edit | Importing contacts, linking contacts already in Autotask, and pushing contacts |
| Opportunities | View, Add, Edit | Pushing opportunities and updating them with auto-sync |
| Resources | View | Listing your Autotask users under Object owner mapping |
| Countries | View | Reading the country on imported addresses |
- Give access to all records, not only the API user’s own. Gabriel sets the owner of each company and opportunity to your mapped user, so a security level limited to records the API user owns can’t update them later.
- Delete isn’t needed. Gabriel never deletes anything in Autotask.
- Import only? If you never push to Autotask, View is enough.
Connect
Section titled “Connect”- Go to Settings > Integrations > PSA Integration.
- Under API credentials, turn on Enable integration.
- Enter the API username and API secret key.
- Click Test connection.
You should see “Successfully connected to Autotask”. A successful test saves the credentials and turns on Enable integration, so you don’t need to save first. The How to connect panel beside the form repeats these steps. Once you’re connected, set the owner and company type mappings, then import.
Once the connection works, the top of the page shows a Connected status line with the API username, when it was last tested and whether auto-sync is on. The rest of the settings are split into four tabs:
- Import: Import companies and Import contacts.
- Sync: Auto-sync to Autotask and Sync issues. The tab shows how many records need attention.
- Mappings: Object owner mapping and Company type mapping.
- Connection: API credentials, Disconnect and the setup steps.
Each tab saves on its own. When you change a setting, a bar appears at the bottom of the screen. Save changes saves only the tab you’re on, and Discard throws away only that tab’s changes. A tab with unsaved changes shows a dot beside its name, and its changes stay there while you work on another tab. If you try to leave the page with unsaved changes on any tab, Gabriel asks first.
To change the secret later, open the Connection tab, type the new one and save. Leave the box blank to keep the current one.

Set who owns records in Autotask
Section titled “Set who owns records in Autotask”Every company created in Autotask needs an owner. On the Mappings tab, under Object owner mapping, match each Gabriel user to an Autotask user (tick Not mapped only to list just the users still to do), pick a Default owner for anyone unmapped, and click Save changes. Gabriel uses the company’s account manager or the opportunity’s assignee, and sets the owner only when the record is first created in Autotask.
Map company types
Section titled “Map company types”On the Mappings tab, under Company type mapping, choose the Autotask company type for each Gabriel company type. It applies every time a company is pushed. Unmapped companies that came from Autotask keep their original type; other unmapped companies become Customer.
Import companies from Autotask
Section titled “Import companies from Autotask”Only admins with the Manage organization settings permission can import. Imports read from Autotask and never change anything there.
- On the Import tab, in Import companies, choose what to bring in:
- Company types to import: open the list and tick the types you want. Leave them all unticked for every type (the box then reads All company types). Click Refresh in the list if a new type is missing.
- Import contacts and Import locations: each company’s contacts and addresses too.
- Include inactive: inactive companies and contacts too.
- To keep your company types and Import contacts choice for next time, click Save changes in the bar at the bottom. Import locations and Include inactive aren’t remembered, so set them each time.
- At the bottom of Import companies, choose one:
- Preview & select: review the companies, expand one to choose its contacts, then click Import N selected. Companies you already have are labeled Already in Gabriel.
- Import all: import everything that matches.
An import with contacts can take up to a minute. It ends with a count of records imported, skipped and not imported.
Import only some contacts
Section titled “Import only some contacts”To bring in particular contacts without whole companies, use Import contacts, beside Import companies on the Import tab:
- Click Add filter and choose a field, a condition and a value, such as Primary contact · is · Yes. Your Autotask user-defined fields are listed too.
- Add more filters if you need them. A contact must match all of them.
- Turn on Include inactive to include inactive contacts.
- Click Preview & select, untick any you don’t want, and click Import N selected. Or click Import all matching.
A contact whose company isn’t in Gabriel brings the company with it, without its other contacts; the preview marks these New company. Turn on Update existing contacts to refresh contacts imported before; otherwise they’re skipped.
Push a company to Autotask
Section titled “Push a company to Autotask”- Open the company and click … (more actions).
- Click Push to Autotask, or Sync to Autotask if it’s already linked.
- Choose what goes with it:
- Sync Contacts (on by default): every contact on the company.
- Sync Opportunities: its opportunities that have an expected close date.
- Click Continue (or Sync Now for a linked company).
The company needs a phone number. If Autotask has a similar company, you see Potential duplicate found: Link & Update links to it and overwrites its name, phone, website, address and type with Gabriel’s; Create New makes a new one. Afterward the company shows Autotask-linked under its name, and an activity records the push and the Autotask ID.
Push an opportunity to Autotask
Section titled “Push an opportunity to Autotask”Open the opportunity, click …, then Push to Autotask (or Sync to Autotask). The option appears once its company is linked. Until the opportunity has an expected close date it’s greyed out, with the reason shown under it.
If the company isn’t in Autotask yet, click Push to Autotask with company instead. It sends the company, the opportunity’s primary contact and the opportunity together. As with a company push, Gabriel first checks Autotask for a company with a similar name and lets you link to it instead of creating a new one. You need permission to edit the company as well as the opportunity.
Keep Autotask up to date automatically
Section titled “Keep Autotask up to date automatically”On the Sync tab, under Auto-sync to Autotask, turn on Enable auto-sync and click Save changes. Editing a linked company, contact or opportunity then updates it in Autotask.
- Only linked records update. New records still need one manual push, and contacts reach Autotask through their company with Sync Contacts on.
- A contact updates when its name, email, phone, title, status or company changes. Other edits, such as tags or owner, aren’t sent.
- Moving a contact to a company that isn’t in Autotask fails until you push that company.
Fix sync issues
Section titled “Fix sync issues”When an automatic update fails, Gabriel marks the record as failed, stops updating it, and notifies every admin with the reason (failures with the same reason within an hour share one notification). Clicking the notification opens the Sync tab. Gabriel tries again only when someone edits the record, once, or an admin clicks Retry.
Sync issues, on the Sync tab, lists each record that needs attention with its Record, Type, Status, Error and Last attempt:
- Failed: fix the cause, then click Retry. Retrying a company sends only the company, not its contacts or opportunities.
- Needs approval: click Push to send it.
- Autotask never confirmed this create: the push may have arrived without Gabriel hearing back, so Gabriel won’t resend it and risk a duplicate. Click Resolve and search Autotask. If the record is there, enter its ID in It exists in Autotask with ID and click Link to Autotask ID. If not, click Mark not created, then Retry.
Turn the integration off or disconnect
Section titled “Turn the integration off or disconnect”- Turn it off: on the Connection tab, turn off Enable integration and click Save changes. Imports, pushes and auto-sync stop, and records keep their links.
- Disconnect: on the Connection tab, under API credentials, click Disconnect, choose whether to tick Also clear Autotask links, and confirm. The saved credentials are removed and the integration and auto-sync turn off. Nothing changes in Autotask. Unless you clear links, reconnecting to the same account picks up where you left off.
Also clear Autotask links unlinks every company, contact, opportunity and location (the box shows how many), and clears the company types to import, both mappings and the default owner. Sync history is kept.
Switch to a different Autotask account
Section titled “Switch to a different Autotask account”While records are linked, Gabriel refuses another account’s credentials (“These credentials belong to a different Autotask account”) so it can’t write over that account’s records. To switch:
- On the Connection tab, click Disconnect, tick Also clear Autotask links, and confirm.
- Enter the new account’s API username and API secret key.
- Click Test connection.
- Set up the owner and company type mappings again on the Mappings tab.
How it works
Section titled “How it works”What an import brings in
Section titled “What an import brings in”| Record | Fields |
|---|---|
| Company | Name, phone, website, active status, company type, industry |
| Contact | First and last name, email, phone, title, active status |
| Location | An Office address on the company: name, street, city, state, ZIP, phone |
- Company types and industries match Gabriel’s by name; new ones are added.
- A company with no website gets its contacts’ most common email domain.
- Addresses are set to the United States.
- Companies match only by their Autotask link, never by name. A company added by hand and then imported becomes a second copy; push it first to link it.
- Already-imported companies and contacts are skipped, but new contacts on them are added.
- An email address belongs to one contact. The preview marks contacts whose email is in use Duplicate email and leaves them unticked. Tick Import anyway to bring them in.
- Imports never write to Autotask.
What a push sends
Section titled “What a push sends”- Company: name, phone, website, primary address, active status and type, plus the owner on first push.
- Contacts already in Autotask are linked, not copied. A contact on the Autotask company with the same email, or the same name where one has no email, is linked and updated with Gabriel’s details.
- Opportunity: title, description, amount, probability, monthly recurring and one-time amounts, expected close date, closed date and primary contact. Its start date is the day the opportunity was created in Gabriel, or its close date if that’s earlier. It starts in Autotask’s default status and stage. Gabriel’s stage and won or lost status are not sent.
- Amounts: Gabriel sends Monthly Revenue (MRR), One-Time Revenue and # Months (the contract term, or 12), and Autotask calculates Total Revenue as monthly revenue × months + one-time revenue. A fixed-price deal, or one with no MRR and no one-time fees, goes as One-Time Revenue equal to its amount. A hand-typed amount that doesn’t match that formula is replaced by Autotask’s total. Cost fields are sent as 0.
Limitations
Section titled “Limitations”- Autotask edits don’t come back on their own. Running Import companies again adds new companies and new contacts but doesn’t update companies already imported. To refresh existing contacts, use Import contacts with Update existing contacts on.
- Opportunities, tickets and contracts can’t be imported.
- Previews are capped at 100 companies and 500 contacts. Use Import all or Import all matching, or narrow by type or filter.
- Only owners and company types can be mapped. Mobile phone and Autotask user-defined fields aren’t synced.
- Opportunity categories that require extra fields in Autotask aren’t supported; Autotask rejects those pushes.
- Automations can’t create Autotask records.
Best practices
Section titled “Best practices”- Admins: map owners and set a Default owner before the first push. Autotask rejects a company it can’t give an owner, and the owner is only set at creation. Tick Not mapped only to check that nobody is missing.
- Import from Autotask before anyone adds companies by hand. A company typed in first and then imported becomes a duplicate.
- Import in batches by company type. Start with Customer and check the results, so a mapping mistake shows before thousands of records come in.
- Use Import contacts for your primary contacts. Primary contact · is · Yes brings in the people you sell to without every contact on every account.
- Fill in expected close dates as deals are created. Without one an opportunity can’t be pushed, and Sync Opportunities skips it.
- Turn on auto-sync once your first pushes look right, then check the Sync tab weekly. A failed record stops updating until someone fixes it, and the tab shows a count whenever records need attention.
- Close deals in Autotask too. Gabriel doesn’t send stage or won and lost status.
- Clear links only when switching accounts. It’s permanent and turns every later push into a duplicate.
Troubleshooting
Section titled “Troubleshooting”| Message | What to do |
|---|---|
| “API username not configured” or “API secret not configured” | Enter both credentials and click Test connection. |
| “Autotask didn’t recognize this API username, so nothing was saved” | Use the API Integration User’s username, ending in @yourdomain.autotask.net. |
| “Autotask authentication failed” | The secret key is wrong or the API user is inactive. Generate a new secret and save it. |
| “Autotask API access denied” | The API user’s security level is missing a permission. Check it against Permissions the API user needs. |
| “Autotask Integration Code is not configured” | Contact Gabriel support to finish setup. |
| “Phone number is required” | Add a phone number to the company. |
| “Its company hasn’t been synced yet” | Push the opportunity’s company first. |
| “An expected close date is required” | Set the opportunity’s expected close date. |
| “Autotask validation error” | Autotask rejected a field, often a missing or inactive owner. Check Object owner mapping and the Default owner on the Mappings tab. |
| “Autotask API rate limit exceeded” | Wait a few minutes and try again. |
| “Autotask integration is not enabled” | An admin needs to turn on Enable integration on the Connection tab. |
| “These credentials belong to a different Autotask account” | See Switch to a different Autotask account. |
| “Autotask acceptance needs review” or “An Autotask create is already reserved” | Resolve the record under Sync issues on the Sync tab. |
