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 VendorId.
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

 
Integer		 
No		 

Specifies 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

 
Integer		 
No		 

Specifies how many items to receive within each page.

By default this is set to our default maximum of 100 items per request.


 
CompanyId

 
Integer		 
No

 
If specified will return a single result for this Company
 
Name


String
No
If specified will retrieve all Companyies 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


Integer		 
The maximum allowed devices for this Company
 
AddSupportUser
Boolean
Indicates 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 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 list of Companies, using XML format.

GET Request   

/api/v2/company/search?format=xml&vendorid=1&integrationkey=xxx

 

XML Response      

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

<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>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>[email protected]</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>