Go to examples:
1. Does the Company already exist in Eploy?
3. Identify Dropdown OptionIDs Needed
4. Insert Company record (POST)
5. Update Company record (PATCH)
Company Sync
Company synchronisation integrations are a good way to ensure that the Company structure in Eploy is always kept up to date with that in your HR system or other platform where master company structure data is maintained.
It often goes hand-in-hand with a Contact/User Sync to ensure that all Hiring Managers are allocated correctly within the Company structure and can access the Eploy Hiring Manager Portal to carry out day-to-day recruitment activities. It is advised that the Company sync happens immediately prior to the Contact/User sync, thereby ensuring that any new/updated Company records are updated before then updating any new/updated manager data.
Generally there are 2 ways to carry out a Company sync, either by carry out the full synchronisation regularly (e.g. on a nightly basis) or by triggering the API process every time Company record is added/modified in the HR system. Either way, the process might look something like this each for each record that needs to be processed:
1. Does the Company already exist in Eploy?
It is recommended that you store a unique identifier in the “Company.Import” field to identify each Company record in relation to the system you are integrating with. This allows you to easily identify the record in Eploy and decide whether you need to insert a new record up update an existing one.
The following search will allow you to find out if a record exists, and if so, what the Eploy CompanyID is.
API ENDPOINT
POST /api/companies/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Filters": [
{
"Operation": "Equals",
"Route": "Company.Import",
"Value": "8a8b8c8d"
}
],
"Paging": {
"RecordsPerPage": 1,
"RequestedPage": 1
},
"ResponseBlocks": [
"CompanyID",
"Name"
]
}
“8a8b8c8d" = The unique identifier of the Company you are creating/updating from the HR system
EXAMPLE RESPONSE
{
"Records": [
{
"CompanyId": 3,
"Name": "Customer Service"
}
],
"TotalPages": 1,
"CurrentPage": 1,
"TotalRecords": 1
}
2. Identify Parent Company ID
Company records in Eploy are related to one another using a parent-child relationship in order to build the company structure. Every Company that forms part of the structure needs to have a ‘ParentCompanyID’, which is the Eploy CompanyID of the direct parent Company record. Therefore, in order to create/update a Company record, you need to know the Eploy CompanyID of the parent, which can be queried in the same way as step 1. above:
API ENDPOINT
POST /api/companies/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Filters": [
{
"Operation": "Equals",
"Route": "Company.Import",
"Value": "9a9b9c9d"
}
],
"Paging": {
"RecordsPerPage": 1,
"RequestedPage": 1
},
"ResponseBlocks": [
"CompanyID",
"Name"
]
}
“9a9b9c9d" = The unique identifier of the direct parent of the Company you are creating/updating from the HR system
EXAMPLE RESPONSE
{
"Records": [
{
"CompanyId": 4,
"Name": "Head Office"
}
],
"TotalPages": 1,
"CurrentPage": 1,
"TotalRecords": 1
}
3. Identify Dropdown OptionIDs Needed
Among the various fields that can be set against a company record, some may be dropdowns. Dropdown fields and the associated options can either be standard or custom, but either way, to set them via the API you need to know the Eploy OptionID for the option you need to set. You may choose to hold these in a mapping table, or you can identify them via the API by performing a search, either on the ‘Description’ of the dropdown item or the ‘Reference’ (a ‘Reference’ value you can set against each dropdown entry to uniquely identify it).
API ENDPOINT
POST /api/options/custom/99/search or POST /api/options/dropdown/99/search
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"Filters": [
{
"Operation": "Equals",
"Route": "Option.Reference",
"Value": "AA"
}
],
"Paging": {
"RecordsPerPage": 1,
"RequestedPage": 1
},
"ResponseBlocks": [
"ID",
"Description",
“Reference”
]
}
/99/ = The Eploy OptionID of the custom Option Type you are querying
“AA" = The unique identifier of the option you are trying to identify from the HR system
Reference / Description may be used to identify the option. Note: use /custom/ for custom Option Types or /dropdown/ for standard Option Types. A full list of available Option Types can be retrieved using GET /api/options/
EXAMPLE RESPONSE
{
"Records": [
{
"Description": "Commercial",
"Id": "1",
"Reference": "AA"
}
],
"TotalPages": 1,
"CurrentPage": 1,
"TotalRecords": 1
}
4. Insert Company record (POST)
If your query in step 1. returned no results, you can insert the Company record using the following:
API ENDPOINT
POST /api/companies
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"BusinessAreaId": 9,
"CompanyStatusId": 9,
"Import": "8a8b8c8d",
"IndustryId": 9,
"LocationId": 9,
"Name": "Eploy Test",
"ParentCompanyId": 999,
"Reference": "12345",
"Address": {
"Address1": "Address1",
"Address2": "Address2",
"Address3": "Address3",
"CountryId": 9,
"County": "County",
"PostCode": "PostCode",
"Town": "Town"
}
}
“8a8b8c8d" = The unique identifier of the Company you are creating from the HR system
999 = The Eploy CompanyID identified in the response to 2. (i.e. the Parent Company)
9 = The Eploy OptionIDs identified in the response(s) to 3.
Variable strings
EXAMPLE RESPONSE
{
"Id": 35,
"Url": "https://testsystem.eploy.net/api/companies/35"
}
5. Update Company record (PATCH)
If your query in step 1. returned a result, you can update the Company record using the following:
API ENDPOINT
PATCH /api/companies/888
HEADERS
Content-Type: application/json
Authorization: Bearer (access_token)
BODY
{
"BusinessAreaId": 9,
"CompanyStatusId": 9,
"Import": "8a8b8c8d",
"IndustryId": 9,
"LocationId": 9,
"Name": "Eploy Test",
"ParentCompanyId": 999,
"Reference": "12345",
"Address": {
"Address1": "Address1",
"Address2": "Address2",
"Address3": "Address3",
"CountryId": 9,
"County": "County",
"PostCode": "PostCode",
"Town": "Town"
}
}
888 = The Eploy CompanyID identified in the response to 1. (i.e. the Company you are updating)
“8a8b8c8d" = The unique identifier of the Company you are updating from the HR system
999 = The Eploy CompanyID identified in the response to 2. (i.e. the Parent Company)
9 = The Eploy OptionIDs identified in the response(s) to 3.
Variable strings
Note: there is no response body for this API call but a 200 response means that you have successfully updated the Company record.
Comments
0 comments
Article is closed for comments.