# CompanyService
This service is used to create and get customer data from the CRM module. The main methods are SaveCompanies (opens new window), GetCompanies (opens new window) and DeleteCompanies (opens new window).
CompanyService (opens new window)
CompanyService WSDL (opens new window)
# Guides
# Retrieve Companies
You can search for companies with any of the available CompanySearchParameters in the method GetCompanies (opens new window). You have to specify which properties you want in return with return properties.
Example of a retrieve request:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetCompanies xmlns="http://24sevenOffice.com/webservices">
<searchParams>
<CompanyId>100</CompanyId>
</searchParams>
<returnProperties>
<string>Name</string>
<string>Country</string>
</returnProperties>
</GetCompanies>
</soap:Body>
</soap:Envelope>
# Retrieving all Company data
The above method is useful for getting updates to Companies or looking up specific Companies using the CompanySearchParameters. However, if you want to do a full inital sync or otherwise get a complete Company list you should use the GetCompanySyncList (opens new window) method. The method provides the following search parameters:
- Page
- Active
- ChangedAfter
- RegisteredAfter
If you want to get a full list of customers (active and deleted) you simply submit the following:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetCompanySyncList xmlns="http://24sevenOffice.com/webservices">
<syncSearchParameters>
<Page>1</Page>
</syncSearchParameters>
</GetCompanySyncList>
</soap:Body>
</soap:Envelope>
This returns the following information:
- CurrentPage (in this case 1)
- TotalPages
- TotalItems
- ItemsPerPage (set to 1000)
- An array of SyncCompanies items
The SyncCompany items contain basic information about the company (like CompanyId and ExternalId). In order to get complete information about the companies you can send a request with (up to) 1000 CompanyIds using the CompanyIds search parameter in the GetCompanies (opens new window) method.
# Save Companies
In order to save a company, all you have to do is submit a Name and a Type to the method SaveCompanies (opens new window). You probably want to add more information than that, but it will get you started. The Types you can choose from are: Consumer (also known as a private customer), Business and Supplier.
By default, the Id of a company is set by 24SevenOffice upon creation. To set your own CompanyId, you must set the ExplicitlySpecifyNewCompanyId property to true. You will be able to specify an Id of your choice. Below are possible combinations and their outcome:
TIP
If you are using .NET you also have to set the hidden property ExplicitlySpecifyNewCompanyIdSpecified to true. This is due to an implementation error in .NET
PLEASE NOTE
You can currently only specify the CompanyId for Business type Companies. Consumer type Companies cannot have custom ID set, they will be converted to Business type Companies.
| Company | ExplicitlySpecifyNewCompanyId | Result |
|---|---|---|
| Exists | true | Exception is thrown |
| Does not exist | true | Company created with Id |
| Deleted | true | Exception is thrown |
| Exists | false (default) | Company is updated |
| Does not exist | false (default) | Any specified Id is ignored, company created and Id automatically set |
| Deleted | false (default) | Company is seemingly created, but nothing happens |
Below is a simple XML example of a request to SaveCompanies (opens new window):
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Body>
<SaveCompanies xmlns="http://24sevenOffice.com/webservices">
<companies>
<Company>
<Name>Test Name</Name>
<Type>Business</Type>
</Company>
</companies>
</SaveCompanies>
</soap:Body>
</soap:Envelope>
# Update Companies
In order to update information for an existing company you submit the Id and the information that you want to update. The ExplicitlySpecifyNewCompanyId property is set to false by default, so you don't have to worry about that when doing a regular update.
TIP
When updating a company you can only switch types between Business and Supplier, you cannot switch types from or to Consumer
# Set an external CompanyId
If you wish to use an external ID in addition to the 24SevenOffice ID, you can use the ExternalId property or the CompanyMap data type that consist of MapType, ExternalId and CompanyId. You use MapType to specify a type of mapping. This is useful if you are mapping several external Id’s. ExternalId is the external Id and CompanyId is the 24SevenOffice Id. Please note that these mapping references are not visible in the 24SevenOffice user interface, but only on a programmatic level through the API.
# Save Bank Account information
You can add Bank account information for a customer through the API by using the SaveCompanies (opens new window) method. However, there are no methods available for updating existing bank account information or removing bank account information. The available fields are:
| Property | Description |
|---|---|
| BankAccountNo | The Bank Account Number |
| BankAccountType | Available values: iban, bban, bankgiro, plusgiro |
| BankAccountCountry | ISO 3166 country code |
| BankAccountBic | Valid BIC code |
In most cases just submitting the Bank Account Number will be sufficient and the API will set Bank Account Type and Bank Account Country automatically. The Bank Account Number that was last saved through the API will be set as default.
PLEASE NOTE
If you try to create a company with invalid bank account information and get a BankAccountException the company will still be created. The API will return the Id of the company in these cases. If you receive other API errors and no new Id is returned, the company was not created
# Set default Bank Account Number
If you want to change the default Bank Account Number, you can add it to your request to SaveCompanies (opens new window). Even if the Bank Account Number has previously been added to a customer, you can change the default account this way.
Example: You've created a Company with Id 123 with Bank Account Number 123456789. This is now the default (and only) account. Later you add Bank Account Number 987654321 to CompanyId 123. Now 987654321 is the default account. If you wish to change the default back to 123456789 you simply send a new request to SaveCompanies for the Company with Id 123 and BankAccountNo 123456789.
# Methods
| Method | Input type | Return type | Description |
|---|---|---|---|
| GetCompanies (opens new window) | CompanySearchParameters, returnProperties[] | Company[] | Returns a list of companies based on the search parameters. You need to specify the return properties. |
| DeleteCompanies (opens new window) | Company[] | Company[] | Deletes an array of companies and returns the ones where a delete error occured. Only the Id-property of Company is required to delete. |
| SaveCompanies (opens new window) | Company[] | Company[] | Saves all the companies in the array. This method also returns all companies, now with the Id if it is a new company. Please see APIException property for any save errors. |
| SaveRelations (opens new window) | Relation[] | Relation[] | Saves an array of relations and returns the ones where an error occured. |
| DeleteRelations (opens new window) | Relation[] | Relation[] | Deletes an array of relations and returns the ones where an delete error occured. |
| SaveMaps (opens new window) | CompanyMap[] | CompanyMap[] | Saves an array of maps and returns the ones where an error occured. |
| DeleteMaps (opens new window) | CompanyMap[] | CompanyMap[] | Deletes an array of maps and returns the ones where an delete error occured. |
| GetStatuses (opens new window) | KeyValuePair[] | Returns a KeyValuePair array of all CRM statuses. Key = StatusId, Value = StatusName | |
| GetCategories (opens new window) | Category[] | Returns an array of all CRM categories. | |
| SaveCategories (opens new window) | Category[] | Save an array of CRM categories. | |
| GetIndustries (opens new window) | KeyValuePair[] | Returns a KeyValuePair array of all Industries. Key = Id, Value = Name | |
| GetCustomerCategoryTree (opens new window) | KeyValuePair[] | Returns a KeyValuePair array of all Companies and their linked categories. Key = CategoryId, Value = CompanyId. | |
| GetCustomerCategories (opens new window) | Int32 | Int32[] | Returns an array of Category Ids linked to the specified customer |
| SaveCustomerCategories (opens new window) | KeyValuePair[] | APIException[] | Saves categories to customers (Key = CategoryId, Value = CompanyId) and returns a list of errors (if any) |
| DeleteCustomerCategories (opens new window) | KeyValuePair[] | APIException[] | Deletes categories from customers (Key = CategoryId, Value = CompanyId) and returns a list of errors (if any) |
| GetCRMGroups (opens new window) | Group[] | Returns a tree list of CRM Groups and sub groups |