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:
| https://www.echospan.com/echotools7/api/api_import_emps.asp |
Import Request Parameters
| Parameter/Field Name | Description/Possible Values | Required |
| Key | Unique 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 | Yes |
| ClientID | A four-digit number provided by EchoSpan used to identify your account. | Yes |
| Cmd | The command you want to send to the API. Options include: I = Insert new employee into the import queue. If employee exists, record will be updated when the queue is processed. U = Queue an updated record for an existing employee. If employee does not exist, a record will be added when the queue is processed. T = Mark employee as terminated P = Process import queue. Send this command after all employee records have been queued (using I, U and T commands) to commit your changes to the employee database. D = Delete import queue | Yes |
| Fname | The first name of the employee to update. This parameter is required for I, U and T Cmd values. | Yes |
| Lname | The last name of the employee to update. This parameter is required for I, U and T Cmd values. | Yes |
| The email address of the employee to update. This parameter is required for I, U and T Cmd values. | Yes | |
| EmpIDNumber | The 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 |
| Title | The title of the employee to update. | No |
| Phone | The phone number of the employee to update. | No |
| Department | The 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 |
| StartDate | The employment start date of the employee to update. | No |
| IsManager | Boolean 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 |
| ManagerEmpIDNumber | The manager's ID number of the employee being updated. This value is used to construct your company's managerial hierarchy. | No |
| APITestForm | Boolean 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 Code | Description |
| 200 | Request successful. |
| 402 | Account is expired or payment is required. |
| 403 | Login invalid. |
| 404 | Export data not found. |
| 451 | Bad employee record submitted. Check that you have submitted all required fields. |
| 452 | Daily limit on API requests reached. |
| 453 | Database server too busy to process request. |
| 454 | Waiting for another call from your account to complete. Retry the request in a few minutes. |
| 455 | Bad API Key/Client ID combination |
| 456 | Duplicate employee IDs exist. Make sure all employees have unique employee IDs. Delete import queue and retry. |
| 457 | Duplicate employee email values exist. Make sure all employees have unique email addresses. Delete import queue and retry. |
195