TABLE OF CONTENTS
The Company API allows you to retrieve, create and delete client Companies on the platform. This enables scenarios where Companies created/maintained in other systems (e.g., SAP, Salesforce) can be replicated to the platform automatically. On our Cloud service, this API is available via SSL secured HTTPS connection using the REST GET, POST and PUT verbs.
The format query string parameter controls the desired response format. Specify either xml or json.
/api/v2/company?format=xml/json
To search for and retrieve multiple Companies at once, use a GET with the search API found at:
/api/v2/company/search?format=xml/json
NOTE: The search API end point implements pagination and, as such, you must cater for this when you connect to our platform. You can learn more about pagination here.
GET Request
The GET verb allows you to retrieve a single Company, identified by its unique Company Id. The required and optional parameters for a GET call to the Company's API are outlined below.
| Parameter Name | Data Type | Required | Description |
| Format | String | Yes | Specifies the desired format of the response. Must be either JSON or XML. |
| Id | Integer | Yes | The unique ID of the company to retrieve |
| VendorId | Integer | Yes | Your unique Master/Vendor account Id found on the Company Setup page of the secure website |
| Integrationkey | String | Yes | Your unique Master/Vendor account Integration Key found on the Company Setup page of the secure website |
GET Response
The data returned from a Company GET is provided as follows:
Company Response (<CompanyResponse>)
| Field Name | Data Type | Description |
| Company | Company | The returned Company object |
| ResponseStatus | ResponseStatus | Details of any errors that may have occurred |
Company (<Company>)
| Field Name | Data Type | Description |
| Id | Integer | Your unique Provider Id found on the Company Setup page of the secure website (under My Account). Required for POST, GET and PUTs |
| Name | String (Max length 100 chars) | A Companys name. Required for POST and PUT actions. |
| Description | String (Max length 300 chars) | A description of the Company. Required for POST and PUT actions. |
| Country | String | The country to which this Company belongs. Required for POST and PUT actions. |
| TimeZone | String | The Companys default time zone. e.g. Pacific Standard Time Required for POST and PUT actions. |
| DateFormat | String | The Company's date display format. Examples include:
|
| TimeFormat | String | The Companys time display format. Examples include:
|
| SendInviteEmailsTo | String | Instructs the system to send all user invite and reset emails to the given email address |
| Status | String | Describes the companys current status.
|
| UserLimit | Integer | The maximum amount of users allowed for this company |
| VendorId | Integer | The unique Master Vendor Id for this Company. Required for all requests. |
| IntegrationKey | String | Your unique Integration Key found on the Company Setup page of the secure website (under My Account) Required for POST and PUT requests. |
| LastUpdated | DateTime | The date and time that the Company was last updated |
| LastUpdatedBy | String | The first and last names of the user that last updated this company |
| ActiveDevices | Integer | The total number of devices currently active |
| ActiveUsers | Integer | The total number of users currently active |
Response Status (<ResponseStatus>)
| Input Name | Data Type | Description |
| ErrorCode | String | The error code/message for the failure |
| Message | String | Description of the error |
| Errors | Collection | Collection of ResponseErrors compiled during the request |
Response Error (<ResponseError>)
| Input Name | Data Type | Description |
| ErrorCode | String | The error code/message for the failure |
| FieldName | String | Name of field involved in error, if any |
| Message | String | Error message |
API Usage Example
Given that the API is REST based, you can access the API directly via your web browser to test it. Obviously for actual integration works, you will need to make a web request to the given REST URL and then parse the response.
Below is a simple GET example which gets a User, using XML format.
GET Request
HTML
/api/v2/company?format=xml&integrationKey=xxx&vendorid=1&companyid=1XML Response XML
<CompanyResponse
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ResponseStatus
xmlns:d2p1="http://schemas.servicestack.net/types" i:nil="true" />
<Company>
<ActiveDevices>1</ActiveDevices>
<ActiveUsers>1</ActiveUsers>
<Country>GB</Country>
<DateFormat>dd-MMM-yyyy</DateFormat>
<DefaultSenderEmail>[email protected]</DefaultSenderEmail>
<DefaultSenderName>Test</DefaultSenderName>
<Description>Test</Description>
<DeviceLimit>0</DeviceLimit>
<GlobalFormPOSTURL />
<GlobalHostedGETURL />
<GlobalTaskPOSTURL />
<Id>2</Id>
<Industry i:nil="true" />
<IntegrationKey>xxx</IntegrationKey>
<LastUpdated>0000-00-00T00:00:00.000Z</LastUpdated>
<LastUpdatedBy>Test, Test</LastUpdatedBy>
<Name>Test</Name>
<SendInviteEmailsTo />
<Status>Active</Status>
<TimeFormat>HH:mm</TimeFormat>
<TimeZone>GMT Standard Time</TimeZone>
<UserLimit>0</UserLimit>
<VendorId>1</VendorId>
</Company>
</CompanyResponse>