GET Company

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 NameData TypeRequiredDescription
FormatStringYesSpecifies the desired format of the response. Must be either JSON or XML.
IdIntegerYesThe unique ID of the company to retrieve
VendorIdIntegerYesYour unique Master/Vendor account Id found on the Company Setup page of the secure website
IntegrationkeyStringYesYour 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 NameData TypeDescription
Company CompanyThe returned Company object
ResponseStatusResponseStatusDetails of any errors that may have occurred


 Company (<Company>)

Field NameData TypeDescription
IdIntegerYour unique Provider Id found on the Company Setup page of the secure website (under My Account).
Required for POST, GET and PUTs
NameString
(Max length 100 chars)
A Companys name.
Required for POST and PUT actions.
DescriptionString
(Max length 300 chars)
A description of the Company.
Required for POST and PUT actions.
CountryStringThe country to which this Company belongs.
Required for POST and PUT actions.
TimeZoneStringThe Companys default time zone. e.g. Pacific Standard Time
Required for POST and PUT actions.
DateFormatStringThe 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
TimeFormatString

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
SendInviteEmailsToStringInstructs the system to send all user invite and reset emails to the given email address
StatusStringDescribes the companys current status.
  • Active
  • Retired
UserLimitIntegerThe maximum amount of users allowed for this company
VendorIdIntegerThe unique Master Vendor Id for this Company.
Required for all requests.
IntegrationKeyStringYour unique Integration Key found on the Company Setup page of the secure website (under My Account)
Required for POST and PUT requests.
LastUpdatedDateTimeThe date and time that the Company was last updated
LastUpdatedByString The first and last names of the user that last updated this company
ActiveDevicesInteger The total number of devices currently active
ActiveUsers Integer The total number of users currently active

 

Response Status (<ResponseStatus>)

Input NameData TypeDescription
ErrorCodeStringThe error code/message for the failure
MessageStringDescription of the error
ErrorsCollectionCollection of ResponseErrors compiled during the request

 

Response Error (<ResponseError>)

Input NameData TypeDescription
ErrorCodeStringThe error code/message for the failure
FieldNameStringName of field involved in error, if any
MessageStringError 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>

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.