Getting Started with Alarm.com Web Services

Setting Up a Test Account

To avoid impacting your customer base as you develop and test your integration, you should ask your sales rep to set up a test dealer for you. This dealer account will exist outside of your current account and allow you to create, modify, and terminate test accounts without fear of impacts to your customer base or billing. The test dealer will be a completely separate account, so you will need to work with your sales rep to make sure the setup mirrors your regular account in permissions and available packages.

Keep in mind that once you are ready to move your code to your "production" dealer account, you will need to make sure any permission and/or role changes you made during testing are replicated.

Creating an API User

All Alarm.com Web Services are authenticated by a Partner Portal login. Because this login requires extremely high permissions, it is recommended that you have a single login that is used only for Web Services calls. This login should be assigned a custom role-specific to API users. There is an API User template you can use to create this role. (See Custom Roles for more details.) Ideally, this login will also have a name that signifies its use as an API-only account.

Format of Requests and Responses

Because Alarm.com APIs are all SOAP-based, your first step will be to use the correct Web Services Definition Language (WSDL) to create a Web Reference in your code base. 

The most commonly used endpoints are:

• https://alarmadmin.alarm.com/webservices/CustomerManagement.asmx?WSDL
• https://alarmadmin.alarm.com/webservices/DealerManagement.asmx?WSDL
• https://alarmadmin.alarm.com/webservices/OrderManagement.asmx?WSDL
• https://alarmadmin.alarm.com/webservices/Validate.asmx?WSDL

These WSDLs will provide all the information your solution needs to correctly form each request and process the resulting response. The endpoints also contain a list of each available method and the XML format for its request and response. Navigating to the EmailWelcomeLetter method 

(https://alarmadmin.alarm.com/webservices/CustomerManagement.asmx?op=EmailWelcomeLetter)

displays the XML format needed for the request.

POST /webservices/CustomerManagement.asmx HTTP/1.1
Host: alarmadmin.alarm.com
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Header>
    <Authentication xmlns="http://www.alarm.com/WebServices">
      <User>string</User>
      <Password>string</Password>
      <TwoFactorDeviceId>string</TwoFactorDeviceId>
    </Authentication>
  </soap12:Header>
  <soap12:Body>
    <EmailWelcomeLetter xmlns="http://www.alarm.com/WebServices">
      <customerId>int</customerId>
    </EmailWelcomeLetter>
  </soap12:Body>
</soap12:Envelope>

To call this method, you will need to  first fill out the required XML fields. In this case, you need to fill out only the Authentication portion (see Authentication) and the customerId. From here, the actual method of performing the call will depend on your software framework, but you can refer to Ways to make a web service call for ways to test out your call.

The format of the response is also described in https://alarmadmin.alarm.com/webservices/CustomerManagement.asmx?op=TerminateCustomer.

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <EmailWelcomeLetterResponse xmlns="http://www.alarm.com/WebServices">
      <EmailWelcomeLetterResult>
        <Success>boolean</Success>
        <ErrorMessage>string</ErrorMessage>
      </EmailWelcomeLetterResult>
    </EmailWelcomeLetterResponse>
  </soap12:Body>
</soap12:Envelope>

Most method responses include Success and ErrorMessage fields that will indicate whether the call you made was successful and if there were any relevant error messages. It is still recommended that you surround all calls with a try/catch clause to account for any errors that may occur.

Authentication

All of Alarm.com’s Web Services use the same authentication scheme. We use a SOAP header that takes in the user name and password of the API user you created under your test account.

Here is some example C# client code:

CustomerManagement ws = new CustomerManagement();
Authentication auth = new Authentication();
auth.User = yourDealerSiteLogin;
auth.Password = yourDealerSitePassword;
auth.TwoFactorDeviceId = your2FactorDeviceId; //(only applicable if you have set this up for your account; otherwise, this can be empty)
ws.AuthenticationValue = auth;

For more information about how to generate and use a web service token, see How to Generate and Use a Web Service Token. 

Ways to Make Web Service Calls

Each software framework has its own way of importing Web Services and calling them. Below are a couple of ways (sometimes referred to as Web References) to test out calls prior to fully implementing them in your software solution.