SwipeClock Public API for TimeWorksPlus and TimeWorks

The following operations are supported. For a formal definition, please review the Service Description.

• CreateSession
  Creates a new session for future calls to this API, given a login and password. This login and password needs to have access to only one client, otherwise please use CreateSessionSelectClient. Returns "true" in Success, and a unique SessionID string in ApiReturn.StringReturnValue if successful. SessionID can be passed into subsequent API calls, and, except if the server is reset, typically is valid for at least several hours.
  • Note: Your session is only valid with the individual server you're connected to, which is chosen from a load balancing pool. You'll get the same server whenever you connect from the same public IP address (or any public IP address that matches on the first three numbers, also known as the same class-C block), but your session most likely cannot be used from another IP address elsewhere on the internet, such as if you were to give your Session ID to another party. If you want to delegate access, use GetOneTimeCredential, which is persisted in our database and can be accessed from any IP address.
  • Security Warning: Your Session ID is a credential, and anyone who has it can take actions on your account. Keep it secure as though it were a password.
• CreateSessionSelectClient
  Creates a new session for future calls to this API and selects a specific client. Mainly useful for accounts that can access data from more than one client. The returned SessionID can be passed into subsequent API calls, and, except if the server is reset, typically is valid for at least several hours.
  • The same IP-address limitation as described in CreateSession also applies here.
  • Parameter "matchfield" determines how to parse clientID, and can be either "EmployerID" (client tag entered on website), "MC2ID" (numeric identifier assigned by MC2), or "ClientName" (directly match on client name).
  • Returns "true" in Success, and a unique SessionID string. if successful.
• EEIDSubmit
  Submit updated information for one or more employees via the EEID API. This web method is fully supported for TimeWorksPlus and TimeWorks clients. Please see and/or request the EEID API documentation for full details on what we expect to see in the Employees parameter, part of which has specific requirements and part of which is free-form. Briefly, the XmlDocument's root should contain at least one Employee node which is somewhat of a free-form document, its actual interpretation governed by a script entered into the client account. Employees will be updated or added as necessary, using the EmployeeCode attribute of the Employee node as the record identifier. Please note there is a 4 megabyte upload limit enforced for each individual call to EEIDSubmit.
• GetActivityFile
  Pulls the activity file for the date range. We auto detect whether the client is using the TimeWorksPlus or the TimeWorks system based on the client's Upgrade Status. Note - only client level accounts can pull TimeWorks formats. For information on pulling an activity file using http post, click here.
• GetFinalizedPayroll
  Gets a single FinalizedPayroll from TimeWorksPlus as a large XML document, marking it as Accepted if it is not yet accepted (which prevents the client from unfinalizing it through the web interface). You need to provide a SessionID (which you'll get from CreateSession or CreateSessionSelectClient) and a FinalizedPayPeriodRecordNumber (which you'll get from GetListOfFinalizedPayrolls). A finalized payroll is our internal representation of a single pay period worth of data, and is very comprehensive, including punches with full auditing information, overtime calculation, employee roster, accrual balances, etc.
• GetListOfFinalizedPayrolls
  Returns a list of all finalized payrolls available in the TimeWorksPlus system for the selected client, and their ID numbers and acceptance status.
• GetOneTimeCredential
  This method supports single sign-on for TimeWorksPlus and TimeWorks. This method generates and returns a temporary one-time password to log another client or supervisor user of your choice into the employer portion of the web site. Once you obtain the credential, have the user perform a normal logon, using it in place of the user's password. This method requires that you know the target user's login, and are either logged in as that user or as a user that has rights to manage that login.
• GetOneTimeCredentialESS
  This method supports single sign-on for Employee Self Service. This method generates and returns a temporary one-time password to log another client or supervisor user of your choice into the employer portion of the web site. Once you obtain the credential, have the user perform a normal logon, using it in place of the user's password. This method requires that you know the target user's login, and are either logged in as that user or as a user that has rights to manage that login.
• GetSiteRuleSet
  Gets information about all TimeWorksPlus rules currently active for a site. Also contains the TimeWorksPlus status of the client. If the site doesn't have a rule set the ActiveRuleSetRevisionNumber property will be zero.
• GetUnfinalizedPayroll
  Gets a Time card report based on date range provided as a large XML document.
• UpdateEmployeeFields
  Updates fields in an employee record, optionally adding a new employee if they don't already exist.
  • sessionID (required) string - This is the session number of the active session. (See CreateSessionSelectClient.)
  • ApplicationID (optional) string - A string that identifies your application. This is saved when changes are made to employees.
  • AddIfNotFound (required) bool - indicate whether or not employee(s) should be added if an existing employee is not found that matches.
  • IdentityField (required) enum - Choose the unique identifier field that should be used when matching employees to your system. Normally this will be the EmployeeCode field.
  • Employees[] (required) - this is an array of EmployeeFieldsToUpdate objects which contains the information needed to identify the employee in SwipeClock as well as an array of fields to update or add. Each EmployeeFieldsToUpdate contains:
    • Identifier (required) - This is the employee's unique identifier. This value is used to identify the employee in SwipeClock.
    • OptionalSecondaryIdentifier (optional) - secondary identifier, most users will not need to use this.
    • FieldsToUpdate[] - this is an array of FieldToUpdate objects. Each field you are updating will be represented by a FieldToUpdate object, which contains the following properties:
      • FieldName (required) - string indicating the field name to update.
      • Value (required) - the new value for the indicated field.
      • EffectiveDate - the default behavior of this field adds an effective date to the change. This will only affect the fields found under the "Employee Data" section of the Employee Setup page. Valid values are dates in string format and the word null. This field is ignored for fields that do not support effective dates (like name fields for example).
  • OptionalSecondaryIdentityField (optional) - Most users will not need to use this. This is another enum indicating a secondary field to use when identifying employees.
  Returns: Success - FALSE indicates that there was at least one problem updating or adding an employee, in which case you would need to check the ValidationFailuresList for information on which employee and field caused the failure. If any fields fail to update, the employee that had the failure should be resubmitted when the problem is corrected.