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 Companys 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 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 Company's 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
DateTimeThe 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=1


XML 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>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>