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 Name | Data Type | Required | Description |
| Company | Company | Yes | The Company that you wish to create 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 |
| SupportUser | User | The support User created (if any) See User documentation for full details of this structure |
| ResponseStatus | ResponseStatus | Details of any errors that may have occurred |
Company (<Company>) Response Fields
The Company returned is only populated with the following fields:
| Field Name | Data Type | Description |
| Id | Integer | Unique identifier of the new Company |
| Status | String | The Company current status - i.e., Active |
| IntegrationKey | String | 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@myorg.com</DefaultSenderEmail> <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@myorg.com</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>