How To Setup American Home Shield with ESC


The ESC integration with American Home Shield (AHS) allows you to automate much of the work involved with being an AHS Contractor. It turns common emails sent to you by American Home Shield into customers and dispatches complete with all the information you are used to receiving.


Before you can configure the AHS integration you will need to complete the following steps.

  • Setup an email address for your incoming AHS dispatches. This email address should be used exclusively for AHS dispatches and nothing else. (*Note: do not use a Gmail account for your incoming AHS dispatches.)
  • Once you have configured the email address, contact your AHS representative and ask them to send your dispatches to that email address with the XML attachment. This is essential. Without the XML attachment to the email the integration will not work.

Once all the components are in place you will have to configure ESC to import your AHS dispatches. This is a three step process:

  • Create an AHS customer.
  • Create additional status codes.
  • Configure the integration.

Lets look at each of these steps individually.

Create an AHS Customer

Open the Customer Center and click on the Add Customer button on the toolbar.  Enter "American Home Shield" int he Company/Last Name field.  Enter as much or as little information you wish for this customer and then click the Save button.

Create Additional Status Codes

Click the Dispatch menu and select Enter Status Codes. Enter the following status codes, one at a time, by clicking the Add New button and entering the following information:

Configure the Integration

After all the status codes have been created, go to the Company menu and select System Setup, then click on the Integrations tab. Click the American Home Shield tab and fill out the following fields as described below.

*Gmail treats emails more like chat conversations than individual messages. For this reason, messages sent from American Home Shield may become grouped together and will not import into ESC proper, if at all.

  • POP3 Server - Enter the address of your POP3 Server here. If you are not sure what your POP3 Server is, you can contact your email provider for this information.
  • POP3 User - Use this field to enter the email account where your American Home Shield dispatches are sent. This account should not be used for any other emails as ESC will read and delete all messages that go to this account.
  • POP3 Password - Enter the password associated with your email account here. 
  • Port - Use this field to set the port used when checking mail. The default port for most providers is 110.
  • Use SSL / Use STARTTLS - Use these boxes to enable SSL or STARTTLS if required by your email provider.
  • Email when Processed - All emails that import successfully will be forwarded to this email address. You might want to look at these when you are first starting the integration to reassure yourself that all the data on the email is being imported correctly.
  • Email for Error - All emails that fail to import correctly will be forwarded to this email address. It is important to look at these emails because they may contain useful information. 
    For example: AHS may send the same dispatch to you more than once to cancel the job or give you other important updates. ESC will reject these emails because it sees the dispatch has already been created. If you don't look at these emails you will not get this information.

    Note: ESC will add the word "Processed" to the beginning of the subject on all emails that are successfully imported. The words "Unable to process" will be added to the subject of all emails that were not able to be imported. This could allow you to use the same email address for both successfully and unsuccessfully imported emails providing you filter them into different folders.
  • Return Display Name - Use this field to set the name that will be used as the sender of the emails forwarded by ESC after they have been read. Specifying this information may allow you to create rules in your email software to help you organize these emails more effectively.
  • Return Email Address - This field allows you to specify which email account the forwarded emails will be sent from. 
  • Customer - Use this field to select the American Home Shield customer that you have entered into the system. If you have not yet created one, please do so from the Customer Center, then return to this screen and select them.

Associate Status Codes

Use the Associate Status Codes screen to associate ESC status codes with American Home Shield status codes. Doing this will allow ESC to send updates to American Home Shield every time you change the status of an AHS dispatch. This should significantly cut down the amount of communication required to give the customer a status update.

Use this guide to help you match the ESC codes with their American Home Shield counterparts:

ESC Code AHS Code
Pending Automated Dispatch Load Successful
Traveling Technician In Route To Customers Location
Working In Progress
Off Job On Hold
Back Order In Progress With Parts On Order
Complete Complete
Scheduled Appointment Set
Reschedule Customer Missed Appointment
Call Again Unable to Contact Customer
Cancelled Cancelled
Arrived Technician Arrived At Customers Location
Replacing In Progress With Need To Replace
Denial Possible Denial

Click OK on the System Setup window when you are finished. You are now ready to start using the AHS Integration.

American Home Shield Integration in Action →

0 people found this helpful



Please sign in to leave a comment.