7/15/24, 5:34 PM
GET Companies (Company
Search)
TABLE OF CONTENTS
GET Request
GET Response
Company Response
Company
Response Status
Response Error
API Usage Example
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 Data Require
Description
Name Type d
Specifies the desired format of the response.
Format String Yes
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
Specifies the page (i.e. the slice) of the result set you wish to receive.
PageNo Integer No By default, all paginated APIs start at PageNo of 0, which is the first page of the
result set.
Specifies how many items to receive within each page.
PageSize Integer No
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
ResponseStatusResponseStatusDetails 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.
String
Name (Max 100 Company name.
chars)
Description String A description of the Company.
(Max 300
1 / 11
7/15/24, 5:34 PM
chars)
Country String The country to which this Company belongs.
TimeZone String The Company's default time zone. e.g. Pacific Standard Time
The Company's date display format.
Examples include:
DateFormat String dd-MMM-yyyy (10 November 2014)
M/d/yyyy (11/10/2014)
ddd, MMM d, yyyy (Mon, Nov 10, 2014)
The Company's time display format.
Examples include:
TimeFormat String HH:mm:ss (16:30:00)
h:mm:ss tt (4:30:00 PM)
SendInviteEmails
String Instructs the system to send all user invite and reset emails to the given email address
To
Describes the company's current status.
Status String 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
Indicates whether a support user should be automatically created when creating this
AddSupportUser Boolean Company.
Only available for POST requests.
Response Status (<ResponseStatus>)
Input NameData TypeDescription
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 NameData TypeDescription
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="[Link]
<ResponseStatus />
2 / 11
7/15/24, 5:34 PM
<TotalRows>3</TotalRows>
<Companies>
<Company>
<ActiveDevices>1</ActiveDevices>
<ActiveUsers>1</ActiveUsers>
<Country>GB</Country>
<DateFormat>dd-MMM-yyyy</DateFormat>
<DefaultSenderEmail>test@[Link]</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@[Link]</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>
3 / 11
7/15/24, 5:34 PM
<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@[Link]</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>
4 / 11
7/15/24, 5:34 PM
GET Company
TABLE OF CONTENTS
GET Request
GET Response
Company Response ()
Company ()
Response Status ()
Response Error ()
API Usage Example
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 Data Requir
Description
Name Type ed
Format String Yes Specifies the desired format of the response. Must be either JSON or XML.
Id Integer Yes The unique ID of the company to retrieve
Your unique Master/Vendor account Id found on the Company Setup page of the secure
VendorId Integer Yes
website
Your unique Master/Vendor account Integration Key found on the Company Setup page
Integrationkey String Yes
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
ResponseStatusResponseStatusDetails of any errors that may have occurred
Company (<Company>)
Field Name Data Type Description
Your unique Provider Id found on the Company Setup page of the secure website (under
Id Integer My Account).
Required for POST, GET and PUTs
5 / 11
7/15/24, 5:34 PM
String
A Companys name.
Name (Max length 100
Required for POST and PUT actions.
chars)
String
A description of the Company.
Description (Max length 300
Required for POST and PUT actions.
chars)
The country to which this Company belongs.
Country String
Required for POST and PUT actions.
The Companys default time zone. e.g. Pacific Standard Time
TimeZone String
Required for POST and PUT actions.
The Company's date display format.
Examples include:
dd-MMM-yyyy (10 November 2014)
DateFormat String 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
The Companys time display format.
Examples include:
String HH:mm:ss (16:30:00)
TimeFormat
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
SendInviteEm
String Instructs the system to send all user invite and reset emails to the given email address
ailsTo
Describes the companys current status.
Status String Active
Retired
UserLimit Integer The maximum amount of users allowed for this company
The unique Master Vendor Id for this Company.
VendorId Integer
Required for all requests.
Your unique Integration Key found on the Company Setup page of the secure website
IntegrationKeyString (under My Account)
Required for POST and PUT requests.
LastUpdated DateTime The date and time that the Company was last updated
LastUpdatedB
String The first and last names of the user that last updated this company
y
ActiveDevices Integer The total number of devices currently active
ActiveUsers Integer The total number of users currently active
Response Status (<ResponseStatus>)
Input NameData TypeDescription
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 NameData TypeDescription
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.
6 / 11
7/15/24, 5:34 PM
GET Request
HTML
/api/v2/company?format=xml&integrationKey=xxx&vendorid=1&companyid=1
XML Response XML
<CompanyResponse
xmlns:i="[Link]
<ResponseStatus
xmlns:d2p1="[Link] i:nil="true" />
<Company>
<ActiveDevices>1</ActiveDevices>
<ActiveUsers>1</ActiveUsers>
<Country>GB</Country>
<DateFormat>dd-MMM-yyyy</DateFormat>
<DefaultSenderEmail>test@[Link]</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>
7 / 11
7/15/24, 5:34 PM
POST Company
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
POST Request
You may use either JSON or XML formats in your request. You indicate this by setting the ContentType HTTP header as
"application/json" or "application/xml." If no ContentType is specified, XML format is assumed. The required and optional
parameters for a POST to the Company API are outlined below.
Note that if you wish to automatically create a support user for your internal use with this Company, you should set the
AddSupportUser property on Company to be True.
Parameter NameData TypeRequiredDescription
The Company that you wish to create
Company Company Yes
See the Company type definition from the GET documentation topic.
POST Response
The data returned from a Company POST is provided as follows:
Company Response (<CompanyResponse>)
Field Name Data Type Description
Company Company The Company created
The support User created (if any)
SupportUser User
See User documentation for full details of this structure
ResponseStatusResponseStatusDetails of any errors that may have occurred
Company (<Company>) Response Fields
The Company returned is only populated with the following fields:
Field Name Data TypeDescription
Id Integer Unique identifier of the new Company
Status String The Company current status - i.e., Active
IntegrationKeyString The new Company unique integration key
VendorId Integer The Master Vendor Id to which the new Company belongs
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 POST example which creates a new Company for the specified Vendor, using XML format.
XML
<Company>
<ActiveDevices>0</ActiveDevices>
<ActiveUsers>0</ActiveUsers>
<AddSupportUser>True</AddSupportUser>
<Country>GB</Country>
<Description>Test Org</Description>
<DateFormat>dd-MMM-yyyy</DateFormat>
<DefaultSenderEmail>test@[Link]</DefaultSenderEmail>
8 / 11
7/15/24, 5:34 PM
<DefaultSenderName>Test Company</DefaultSenderName>
<DeviceLimit>0</DeviceLimit>
<GlobalFormPOSTURL></GlobalFormPOSTURL>
<GlobalHostedGETURL></GlobalHostedGETURL>
<GlobalTaskPOSTURL></GlobalTaskPOSTURL>
<IntegrationKey>xxx</IntegrationKey>
<Name>Test Company</Name>
<VendorId>1</VendorId>
<TimeFormat>HH:mm</TimeFormat>
<TimeZone>GMT Standard Time</TimeZone>
<UserLimit>0</UserLimit>
</Company>
XML Response:
<CompanyResponse>
<ResponseStatus />
<Company>
<Id>2</Id>
<IntegrationKey>xxx</IntegrationKey>
<Status>Active</Status>
<VendorId>1</VendorId>
</Company>
<SupportUser>
<Email>2$test@[Link]</Email>
<FirstName>Test Company</FirstName>
<Id>00000000-0000-0000-0000-000000000000</Id>
<LastActivity>0001-01-01T00:00:00</LastActivity>
<LastName>Support</LastName>
<CompanyId>2</CompanyId>
<Status>Invited</Status>
</SupportUser>
</CompanyResponse>
9 / 11
7/15/24, 5:34 PM
PUT Company
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
PUT Request
The PUT verb allows you to update a single, existing Company on the platform. You may use either JSON or XML
formats in your request. You indicate this by setting the ContentType HTTP header as "application/json" or
"application/xml". If no ContentType is specified, XML format is assumed. The required and optional parameters for a
PUT to the Company API are outlined below.
Parameter Data Require
Description
Name Type d
The Company that you wish to update
Company Company Yes See the Company type definition from the GET documentation
topic
PUT Response
The data returned from a Company PUT is provided as follows:
Company Response (<CompanyResponse>)
Field Name Data Type Description
Company Company The Company updated.
ResponseStatusResponseStatusDetails of any errors that may have occurred
Company (<Company>) Response Fields
The Company returned is only populated with the following fields:
Field Data
Description
Name Type
Id Integer The Company's unique identifier
Status String Status of this Company.
Integratio
String The Companys unique integration key
nKey
The Master Company's Id to which the
VendorId Integer
updated Company belongs
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 PUT example which updates an existing Company, using XML format.
<Company>
<ActiveUsers>4</ActiveUsers>
<Id>2</Id>
<IntegrationKey>xxx</IntegrationKey>
<Name>Test Company</Name>
<VendorId>1</VendorId>
</Company>
10 / 11
7/15/24, 5:34 PM
XML Response
<CompanyResponse xmlns:i="[Link]
<ResponseStatus/>
<Company>
<Id>2</Id>
<IntegrationKey>xxx</IntegrationKey>
<Status>Active</Status>
<VendorId>1</VendorId>
</Company>
</CompanyResponse>
11 / 11