Manage employee records with the EchoSpan API

Product Guides for EchoSpan 360-Degree Feedback

Clients have the ability to automate their employee roster updates via the API employee import feature. By using the API import tool you can add, remove or modify employee records in your EchoSpan account database.

This API feature allows you to insert, update or remove an employee record in your EchoSpan database using our REST web service. You can make API calls to EchoSpan using an HTTPS POST request.

Requests are posted for one employee record at a time. A loop in your post request code can be implemented to perform batch operations. When submitting employee records to be processed, all requests are queued for processing and require that you send a "P" command (explained below) to confirm and process the import queue.

In order to use the API, you will need a current EchoSpan Enterprise edition account as well as valid values for all required parameters. Note that some accounts may have limits on the number of imports that can be processed per day. Please check with your client manager about these or other limitations.

To configure an API user import request, direct your HTTPS POST request to the following URL:

Import Request Parameters

Parameter/Field NameDescription/Possible ValuesRequired
KeyUnique 36 character string provided by your client manager used to validate your account's API privileges. This value can be passed either as a form field named "key" or as an HTTP header named "Authorization".

Example: 7AEA2F04-2725-4B7B-9623-1A698EZF24A8
ClientIDA four-digit number provided by EchoSpan used to identify your account.Yes
CmdThe command you want to send to the API. Options include:
I = Insert new employee. If employee exists, record will be updated.
U = Update existing employee. If employee does not exist, a record will be added.
T = Mark employee as terminated
P = Process import queue. Send this command after all employee records have been queued to commit your changes to the employee database.
D = Delete import queue
FnameThe first name of the employee to update. This parameter is required for I, U and T Cmd values.Yes
LnameThe last name of the employee to update. This parameter is required for I, U and T Cmd values.Yes
EmailThe email address of the employee to update. This parameter is required for I, U and T Cmd values.Yes
EmpIDNumberThe employee ID number of the employee to update. This value must unique for each user. Failure to provide a unique value will result in an error. This parameter is required for I, U and T Cmd values.Yes
TitleThe title of the employee to update.No
PhoneThe phone number of the employee to update.No
DepartmentThe department of the employee to update. If the department name value does not already exist in the database, a new department will be created.No
StartDateThe employment start date of the employee to update.No
IsManagerBoolean value (1/0). This value tells the system if the user is a manager of others (1) or an independent contributor (0). When ommitted, the system will set a default value of 0.No
ManagerEmpIDNumberThe manager's ID number of the employee being updated. This value is used to construct your company's managerial hierarchy.No
APITestFormBoolean value (1/0). When set to 1, the API will output status codes and messages to the browser window. This setting should only be set to 1 for testing. Set it to 0 when running production scripts.

Important API Status Codes

Status CodeDescription
200Request successful.
402Account is expired or payment is required.
403Login invalid.
404Export data not found.
451Bad employee record submitted. Check that you have submitted all required fields.
452Daily limit on API requests reached.
453Database server too busy to process request.
454Waiting for another call from your account to complete. Retry the request in a few minutes.
455Bad API Key/Client ID combination
456Duplicate employee IDs exist. Make sure all employees have unique employee IDs. Delete import queue and retry.
457Duplicate employee email values exist. Make sure all employees have unique email addresses. Delete import queue and retry.

Last updated: Wednesday, May 23, 2018
api, API, employee record, https post
Our website uses cookies
Cookies enable us to provide the best experience possible and help us understand how visitors use our website. By browsing EchoSpan, you agree to our use of cookies.
I Understand More Info