Skip to main content

Eploy RESTful API: Contact/User Sync

Integrations
Updated

Go to examples:

1. Does the Contact already exist in Eploy?

2. Identify Manager’s Company ID

3. Identify Dropdown OptionIDs needed

4. Insert Contact record (POST)

5. Update Contact record (PATCH)

6. Insert User record (POST)

7. Update User record (PATCH)

Contact/User Sync

A Contact and User Sync can be used to ensure that all your managers have access to the Eploy Hiring Manager Portal to carry out day-to-day recruitment activities. It can also ensure manager details are kept up-to-date (e.g. changes of name/email address are synchronised into Eploy). If a manager changes department, the integration can ensure their record is moved so that their level of access to in the Hiring Manager Portal is updated accordingly. Likewise, if a manager leaves or moves to a non-management role, the integration can be used to archive their Contact record and deactivate their user, thereby automatically revoking access to the Hiring Manager Portal.

As with the Company sync, a Contact/User Sync could either be ran on a regular schedule, or if could react to changes made to individual records in third-party system. Either way, the process may looks something like this:

flow3.png

1.   Does the Contact already exist in Eploy?

It is recommended that you store a unique identifier in the “Contact.Import” field to identify each manager’s Contact 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 ContactID is.

API ENDPOINT

POST /api/contacts/search

HEADERS

Content-Type: application/json

Authorization: Bearer (access_token)

BODY

{
    "Filters": [
        {
            "Operation": "Equals",
            "Route": "Contact.Import",
            "Value": "7a7b7c7d"
        }
    ],
    "Paging": {
        "RecordsPerPage": 1,
        "RequestedPage": 1
    },
    "ResponseBlocks": [
        "ContactID",
        "Firstname" ,
        "Surname",
        "LinkedUsers"
    ]
}

“7a7b7c7d" = The unique identifier of the manager’s Contact you are creating/updating from the HR system. Note: If an existing Contact is identified, the “LinkedUsers” object in the response will tell you if the existing Contact has an associated User (and the UserId if one exists).

EXAMPLE RESPONSE

{
    "Records": [
        {
            "ContactId": 4,
            "LinkedUsers": [
                {
                    "Id": 30,
                    "Url": "https://testsystem.eploy.net/api/users/30"
                }
            ],
            "FirstName": "Shafquat",
            "Surname": "Panesar"
        }
    ],
    "TotalPages": 1,
    "CurrentPage": 1,
    "TotalRecords": 1
}

2.   Identify Manager’s Company ID

You need to know which Eploy CompanyID your manager’s Contact need to be assigned to in order to create/update them accordingly. This can be done by performing a Company search using the unique identifier of the manager’s Company record from the system you are integrating with.

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 from the HR system that the Contact belongs to.

EXAMPLE RESPONSE

{
    "Records": [
        {
            "CompanyId": 3,
            "Name": "Customer Service"
        }
    ],
    "TotalPages": 1,
    "CurrentPage": 1,
    "TotalRecords": 1
}

3.   Identify Dropdown OptionIDs needed

Among the various fields that can be set against a contact 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": "Area Manager",
            "Id": "1",
            "Reference": "AA"
        }
    ],
    "TotalPages": 1,
    "CurrentPage": 1,
    "TotalRecords": 1
}

4.   Insert Contact record (POST)

If your query in step 1. returned no results, you can insert the Contact record using the following:

API ENDPOINT

POST /api/contacts

HEADERS

Content-Type: application/json

Authorization: Bearer (access_token)

BODY

{
  "Import": "7a7b7c7d",
  "CompanyId": 999,
  "Email": "helloworld@eploy.co.uk",
  "FirstName": "Eploy",
  "Surname": "Test",
  "ContactPositionId":9
}

“7a7b7c7d" = The unique identifier of the Contact you are creating from the HR system  

999 = The Eploy CompanyID identified in the response to 2. (i.e. the Manager’s 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 Contact record (PATCH)

If your query in step 1. returned a result, you can update the Contact record using the following:

API ENDPOINT

PATCH /api/contacts/888

HEADERS

Content-Type: application/json

Authorization: Bearer (access_token)

BODY

 {
  "Import": "7a7b7c7d",
  "CompanyId": 999,
  "Email": "helloworld@eploy.co.uk",
  "FirstName": "Eploy",
  "Surname": "Test",
  "ContactPositionId":9
}

 

888 = The Eploy ContactID identified in the response to 1. (i.e. the Contact you are updating)  

“7a7b7c7d" = The unique identifier of the Contact you are updating from the HR system  

999 = The Eploy CompanyID identified in the response to 2. (i.e. the Manager’s 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 Contact record.

6.   Insert User record (POST)

If your query in step 1. returned no results (or if the existing Contact has no user), you can insert a User record using the following:

API ENDPOINT

POST /api/users

HEADERS

Content-Type: application/json

Authorization: Bearer (access_token)

BODY

{
  "UserTypeId": 2,
  "Username": "EployTestHM",
  "CompanyId": 999,
  "ContactId": 888,
  "CityId": 43,
  "DisplayName": "Eploy Test",
  "Email": "helloworld@eploy.co.uk",
  "CopyPermissionsFromUserId": 4
}

888 = The Eploy ContactID  

999 = The Eploy CompanyID  

2 = The User Type (2 = ”Hiring Manager”)  

43 = The CityId to identify the timezone (43 = "(UTC) Dublin, Edinburgh, Lisbon, London", or use GET /api/options/dropdown/178 for others)  

4 = Any other UserID to copy permissions from  

Variable strings

EXAMPLE RESPONSE

{
    "Id": 29,
    "Url": "https://testsystem.eploy.net/api/users/29"
}

7.   Update User record (PATCH)

If your query in step 1. returned a result with a LinkedUser, you can update the User record using the following:

API ENDPOINT

PATCH /api/users/777

HEADERS

Content-Type: application/json

Authorization: Bearer (access_token)

BODY

 {
  "UserTypeId": 2,
  "Username": "EployTestHM",
  "CompanyId": 999,
  "ContactId": 888,
  "CityId": 43,
  "DisplayName": "Eploy Test",
  "Email": "helloworld@eploy.co.uk",
  "CopyPermissionsFromUserId": 4
}

777 = The Eploy UserID identified in the response to 1. (i.e. the User you are updating)  

888 = The Eploy ContactID  

999 = The Eploy CompanyID  

2 = The User Type (2 = ”Hiring Manager”)  

43 = The CityId to identify the timezone (43 = "(UTC) Dublin, Edinburgh, Lisbon, London", or use GET /api/options/dropdown/178 for others)  

4 = Any other UserID to copy permissions from  

Variable strings

 Note: there is no response body for this API call but a 200 response means that you have successfully updated the Contact record. 

Related articles

Comments

0 comments

Article is closed for comments.