Go to full article

Overview

Prior to making any API calls, the application is required to authenticate with Emersion. Authentication is facilitated via the end user portal login. Even if you do not have an End User Portal from Emersion, you must grant them access since the API uses this infrastructure so the applications can carry out the necessary authentication. 

Authentication is now achieved using the login call under the Authentication end point. A session token is returned. This token must then then be used in every subsequent API call and sessions are automatically set to expire 12 months after they are created.

To retrieve a token:

In the prior versions of the End User APIs, the end user's username and password was required to be supplied in every call. This method is deprecated.

  1. Create a login request()
  2. Specify the customer's end user portal username or account ID.
  3. Specify the customer's end user portal password.

WDSL

https://userapi.emersion.com/Authentication.wsdl

Operation name

Authentication/login



Business Rules

The customer's account must be in an active state.




SOAP Example

An example of a successful authentication.

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:emersion:userapi">
   <soapenv:Header/>
   <soapenv:Body>
      <urn:login>
         <urn:username>sharoncarpenter@emersion.com.au</urn:username>
         <urn:password>abc123</urn:password>
      </urn:login>
   </soapenv:Body>
</soapenv:Envelope>

Response

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="urn:emersion:userapi">
   <SOAP-ENV:Body>
      <ns1:loginResponse>
         <ns1:token>b6d3c923fc8aefb1ba9cef086684efde74d4c21277615ba917b8ecf4270daf64</ns1:token>
      </ns1:loginResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>




Error Handling

This table lists specific errors and faults unique to this operation. If an error is encountered is not listed here, it is likely to be a generic error or fault. 

ErrorDescription
Invalid username / passwordThe system cannot authenticate the end user. Check to ensure that the end user account has end user portal access and that the user ID and password for the account are correct.




Field Descriptions

All field names are case sensitive. Check enumerated values in the descriptions to confirm capitalisation and spacing. See field types for additional information.

NameDescriptionRequired?Field Type

Character

limit

Values 
username
The end user portal username belonging to the customer. You can use the account_id in this field.YesString80

e.g. The customer's username; or

the account ID

password
The end user portal password belonging to the customer. you can also use the account_id in this field.YesString73a case-sensitive string