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 | 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 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:
|
| TimeFormat | String | The Company's time display format. Examples include:
|
| 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.
|
| 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 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&vendorid=1&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>