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
To configure an API export request, direct
your HTTPS POST request to the following URL:
API Request Parameters
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".
number provided by EchoSpan used to identify your account.
you want to send to the API. Options include:
= Insert new employee. If employee exists, record will be
U = Update existing employee. If
employee does not exist, a record will be added.
= 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
name of the employee to update. This parameter is required for
I, U and T Cmd values.
||The last name
of the employee to update. This parameter is required for I, U
and T Cmd values.
address of the employee to update. This parameter is required
for I, U and T Cmd values.
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.
||The title of
the employee to update.
number of the employee to update.
department of the employee to update. If the department name
value does not already exist in the database, a new department
will be created.
employment start date of the employee to update.
(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.
ID number of the employee being updated. This value is used to
construct your company's managerial hierarchy.
(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 Status Codes
expired or payment is required.
Export data not found.
record submitted. Check that you have submitted all required
on API requests reached.
server too busy to process request.
another call from your account to complete. Retry the request in
a few minutes.
Key/Client ID combination
employee IDs exist. Make sure all employees have unique employee
IDs. Delete import queue and retry.
employee email values exist. Make sure all employees have unique
email addresses. Delete import queue and retry.
Reports are running for the account, so the API
cannot make updates. Try again after reports have