API: Employee Database Operations

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*

API 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
UseQString	Boolean value (1/0). When set to 1, the API will GET parameters and values from the querystring. Default is 0, which instructs the API to expect a POST transaction.	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 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.