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: This 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.


GET Request

The GET verb allows you to retrieve multiple Companies, identified by your unique Vendor Id. The required and optional parameters for a GET call to the Company Search 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.
VendorId
Integer
Yes
Your unique Master account's Company Id
Integrationkey
String
Yes
Your unique Master account's Integration Key
 PageNo
IntegerNoSpecifies the page (i.e. the slice) of the result set you wish to receive.
By default, all paginated APIs start at PageNo of 0, which is the first page of the result set.
 PageSize
IntegerNo Specifies how many items to receive within each page.
By default this is set to our default maximum of 100 items per request.
CompanyId
IntegerNo
 If specified will return a single result for this Company
 Name
StringNoIf specified will retrieve all Companies whose Name's contain the specified value

GET Response

The data returned from a CompanySearch GET is provided as follows: 

Company Response (<CompanyResponse>)

Field Name
Data Type
Description
Companies
Companies
The returned collection containing all the Company objects
ResponseStatus
ResponseStatus
Details of any errors that may have occurred
 TotalRows
 Integer The total number of Companies available for your request parameters

Company (<Company>)

Field Name
Data Type
Description
Id
Integer
Unique Company Id found on the Company Setup page of the secure website.
Name
String
(Max 100 chars)
Company name.
Description
String
(Max 300 chars)
A description of the Company.
Country
String
The country to which this Company belongs.
TimeZone
String
The Company's default time zone. e.g. Pacific Standard Time
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)
TimeFormat
String
The Company's time display format. 
Examples include:
  • HH:mm:ss (16:30:00)
  • h:mm:ss tt (4:30:00 PM)
SendInviteEmailsTo
String
 Instructs the system to send all user invite and reset emails to the given email address
Status
String
Describes the company's 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.
IntegrationKey
String
The unique Integration Key for this Company.
 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
 DeviceLimit
IntegerThe maximum allowed devices for this Company
 AddSupportUserBooleanIndicates whether a support user should be automatically created when creating this Company.
Only available for POST requests.

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 Response Errors 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 list of Companies, using XML format.


GET Request  

HTML

<code>/api/v2/company/search?format=xml&amp;vendorid=1&amp;integrationkey=xxx</code>


XML Response      

XML

<CompanySearchResponse  xmlns:i="http://www.w3.org/2001/XMLSchema-instance"><ResponseStatus /> <TotalRows>3</TotalRows> <Companies> <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> <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>3</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> <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>4</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> </Companies> </CompanySearchResponse>