API: Employee Database Operations

Managing employee records with the EchoSpan API.

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 export request, direct your HTTPS POST request to the following URL:

https://*PLEASE REQUEST URL FROM CLIENT MANAGER*

Export 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. 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. When this command is running, your employee database is being updated and users may momentarily not be able to log into the system. So, it's recommended that you execute the P command only after all employee records have been queued and during hours of low user volume. Do not run the P command after every I, U, or T command.
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
Email 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. No

Important Export 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.
458 Reports are running for the account, so the API cannot make updates. Try again after reports have completed.