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.

To search for and retrieve multiple Companys at once, use a GET with the search API found at:

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 in our API overview section.


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 Companys API are outlined below.

Parameter Name

Data Type

Required

Description

Format

String

Yes

Specifies the desired format of the response.
Must either JSON or XML.

IdIntegerYesThe 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 Companys date display format. 

Examples include: 


  • dd-MMM-yyyy (10 November 2014)
  • M/d/yyyy (11/10/2014)
  • ddd, MMM d, yyyy (Mon, Nov 10, 2014)

Please note that data imported into the system relating to date/time information will be required to be in the specified format


TimeFormat

String

The Companys time display format. 


Examples include: 


  • HH:mm:ss (16:30:00)
  • h:mm:ss tt (4:30:00 PM)

Please note that data imported into the system relating to date/time information will be required to be in the specified format

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. 


  • Active
  • Retired

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    

/api/v2/company?format=xml&integrationKey=xxx&vendorid=1&companyid=1

    XML Response     




<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>test@myorg.com</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>