ContactsLaw REST API Documentation

Introduction

The ContactsLaw REST API allows a limited subset of operations to be performed in the context of a particular user or service account.

It is a component of the ContactsLaw Daemon, which runs on the application server (usually located on-premises). Additional infrastructure may be required to access the API remotely.

Authentication

A client access token must be sent with every request (except for the operations relating to authentication). The token is obtained through one of the following operations:

• GET api/Authenticate (Integrated Windows Authentication)
• POST api/Authenticate (Credentials)
• GET api/OAuth2 (OAuth 2.0)

The access token can be included with the request in one of two ways:

• In the Authorization request header, using the Bearer scheme, e.g.

  GET /api/Me HTTP/1.1
  Host: localhost
  Authorization: Bearer c29tZSBhY2Nlc3MgdG9rZW4gdGhhdCBpIGFtIGluY2x1ZGluZyBub3c=

• As the query parameter accessToken, e.g.

  https://localhost/api/Me?accessToken=c29tZSBhY2Nlc3MgdG9rZW4gdGhhdCBpIGFtIGluY2x1ZGluZyBub3c%3D

Access tokens are valid for a limited period and may expire. You should be prepared to re-authenticate whenever you receive a 401 Unauthorized status from another operation.

Content Types

The preferred content type for request/response bodies is application/xml. Many operations also support application/json.

Use the Accept request header to specify the desired content type for the response. If this header is not set, the server will try to respond using the same content type as the request body.

Unless otherwise stated, the XML root element is <Request> for request bodies and <Response> for response bodies. When using JSON, simply omit the root element.

Exceptions

In the event that an operation returns the 500 Internal Server Error status instead of a more specific error, the response body will contain information about the exception that was thrown by the server:

Content Type: application/xml or application/json

<Response>                       
  <Exception>                    
    <Type>string</Type>          <!--Type name of the exception that was thrown--> 
    <Message>string</Message>    <!--The exception message--> 
  </Exception>                   
</Response>                      

{                           
   "Exception": {           
      "Type": "string",     // Type name of the exception that was thrown
      "Message": "string"   // The exception message
   }                        
}