Application Programming Interface (API) for Developers

Overview

The LeaseAccelerator API combines the simplicity of REST requests with the robust data exchange capabilities of XML Remote Procedure Calls (RPC). Each request is stateless and multiple method requests can be submitted concurrently from the same secure session.

Access is secured by SAML2, allowing for instantiation of a secure session that can then be used for multiple requests. To support this secure access, you must be integrated with LeaseAccelerator’s Single Sign-On (SSO) solution. Assuming you already have a SAML2-compliant identity provider configured, this is generally a simple matter of exchanging SAML2 Metadata, consisting of certificate and configuration information. For more information on SAML2, see the OASIS standards at http://saml.xml.org/saml-specifications.

Download a PDF version of the guide.

Authentication

Before you can submit API requests, you must first authenticate through LeaseAccelerator’s SAML2 authentication layer. Assuming your identity provider supports Enhanced Client or Proxy (ECP) mode, this is a straightforward process:

You will need the URL for your identity provider (IdP).
You will need appropriate login credentials for a user who has already been federated for access in LeaseAccelerator.
You will need the URL for the LeaseAccelerator authentication service provider (SP): https://environment.leaseaccelerator.com/auth/api
Submit a SAML2 GET request to the SP URL, identifying the IdP and the credentials you wish to use.
Extract the response, which will take the form of a text security token.

If you are using Java, you may find the shib-http-client project (https://github.com/DARIAH-DE/shib-http-client) useful. The source for a complete Java test client using this library is provided as an appendix to this document. The key fragment implementing the last two steps above is as follows:

HttpClient client= new ShibHttpClient(idpBaseUrl + "/idp/profile/SAML2/SOAP/ECP", userName, password);

HttpGet req = new HttpGet(spUrl + "/auth/api");

HttpResponse res = client.execute(req);

InputStream ins = res.getEntity().getContent();

BufferedReader br = new BufferedReader(new InputStreamReader(ins));

String token = br.readLine();

Structure

URL

Once you have authenticated, and have a valid session, you can submit POST requests using the URL form:

https://environment.leaseaccelerator.com/lease_accelerator/api/LeaseAccelerator/operation

environment is the LeaseAccelerator environment you are accessing (e.g.,www for production). If posting to a different environment, please contact LeaseAccelerator Support for the appropriate URL.
operation is the operation key for the method you are invoking.

Each POST request must include two fields:

token is the security token you received upon successful authentication.
file is an APIRequest tag; see the Request section immediately following for more details.

For the AttachFile operation, there is a third field which is required:

filetoattach is the actual file (e.g., PDF) to be attached.

The response to your POST request will be an APIResponse tag; see the Response section for more details.

Request

The generic structure of a LeaseAccelerator API request is:

<RequestId>requestId</RequestId>

<WarningPolicy>warningPolicy</WarningPolicy>

<ErrorPolicy>errorPolicy</ErrorPolicy>

</Request>

<Payload>operationSpecificRequest</Payload>

</APIRequest>

RequestID	Text	The unique identifier you specified in the request.
requestId	Text	A unique identifier that you use to track the request. It will be included in the response to your request, whether successful or not.
warningPolicy	Stop Skip Ignore	Dictates how LeaseAccelerator should behave if a warning is encountered in processing the request. Stop means that all processing should stop immediately, and any actions performed so far for this request should be rolled back. Ignore means that processing should continue, ignoring any and all warnings that may be reported. The warnings will still be reported back as part of the APIResponse, but processing will continue nonetheless. Skip means that, for multi-record requests, the record that triggered the warning should be skipped, but all other records should still be processed normally. (For requests that accept only one record in the Payload, Skip is not supported.) For example, when doing a bulk import, a warning is raised if no Asset User is specified for an asset. With a warningPolicy of Stop, the import would fail, with neither deals nor assets imported. With a warningPolicy of Ignore, all deals would be imported, albeit some without an Asset User. With a warningPolicy of Skip, all deals would be imported except for those containing an asset for which no Asset User was specified. In all three cases, the APIResponse would detail which deals include assets that have no Asset User specified. The default warningPolicy is Ignore.
errorPolicy	Stop Skip	Dictates how LeaseAccelerator should behave if an error is encountered in processing the request. Stop means that all processing should stop immediately, and any actions performed so far for this request should be rolled back. Skip means that, for multi-record requests, the record that triggered the error should be skipped, but all other records should still be processed normally. (For requests that accept only one record in the Payload, Skip is not supported.) For example, when doing a bulk import, an error is raised if an invalid product category is specified for an asset. With an errorPolicy of Stop, the import would fail, with neither deal nor assets imported. With an errorPolicy of Skip, all deals would be imported except for those for which an invalid product category was specified for an asset. In both cases, the APIResponse would identify each invalid product category specified. The default errorPolicy is Stop.
operationSpecificRequest	XML	The XML request payload specific to the method being invoked. See the Methods section below for details on each method’s specific request payload requirements.

Response

The generic structure of a LeaseAccelerator API response is:

<RequestId>requestId</RequestId>

<Status>requestStatusCode</RequestStatus>

<Context>requestStatusDetails</RequestContext>

<Payload>operationSpecificResponse</Payload>

</APIResponse>

requestId	Text	The unique identifier you specified in the request.
requestStatusCode	Integer	A code indicating success or failure. Zero (0) always means success. Any other value represents an error.
requestStatusDetails	Text	A description of the overall request results. Ok always means success. Any other value is a description of the error encountered.
operationSpecificResponse	XML	The response payload specific to the method being invoked. See the Methods section below for details on each method’s specific response payload.