API - Company Import/Synchronize

The XML company import is available through an endpoint on the eRecruiter API, if you have the "Companies" access level granted for your API key.

General data structure

  • One account has many locations.
  • One location can have none, one or more contacts.
  • A contact must be assigned to one location.


The input file must be a well-formed XML document and valid against the specified XML schema. Have a look at the schema for a more detailed description of the fields.

REST web service

company import REST endpoint
PUT Api/Synchronize/Company?isValidationOnly=(false|true)&requestTimeout=(number)
HTTP request - body
    XMLContent: "..."
HTTP response - body parameters
    StatusType Status,
    SyncResult Result
Type definitions
enum StatusType 
    ValidData = 1,
    InValidData = 2,
    PeristingSkipped = 4,
    PersistingError = 8,
    PersistingSuccess = 16,
    string Identifyer,
    string Type,
    Message[] Messages,
    SyncResult[] NestedResults
    string Text,
    Severity Severity
enum Severity

The type definitions can also be found on GitHub.

XML Schema

Import process

The import operation is an update operation too. For each data element in the XML, the importer tries to find an already existing similar data record in the eRecruiter database. If a data record is found, the attributes are updated with the values of the data element in the import XML. If no existing data record is found, a new data record is created. The following list describes which entities are identified by what property.


A company entity is identified by the ExternalId property. If the existing data record matches the ExternalId of the import element, all values in the import element are stored to the existing data record.


Documents are identified by following three attributes:

  • DocumentTypeName
  • FileName
  • FileExtension

It's just possible to update the file content of the document.

Custom fields

The custom field is identified by it's Name. The value will be updated or created if the custom field exists in the eRecruiter, otherwise an error will be returned. The value is also validated.


A location is identified by the following attributes:

  • Street
  • ZipCode
  • City


The contact entity is identified by the UserName property. The contact will be looked up in the company's context. If any contact is found, it will be assigned to the location, which is hierarchically above it. A contact can change the location withing a company. If no contact with the same username is found, a new data record is created.


A contact's phone is identified by its PhoneNumber. It will be either updated or created.


A contact's email is identified by its EmailAdress. It will be either updated or created.

API-Client and usage

The company import can be called using the API command line client, which can be found on Github. The tool must be called with following command line parameters:

usage of company import
--RunCompanySynchronization --XmlCompanySource PATH/TO/IMPORT.xml --ApiKey THE123API456KEY789 --ApiUrl "http://URL.TO/Api" --MandatorId ID --RequestTimeout 3600

The server and client side timeout is set to the timeout of the parameter RequestTimeout (in seconds). It's recommended to use the timeout parameter, due to a time consuming data synchronization operation.