API12 Web Service

API12

Click here for a complete list of operations.

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.

Test

The test form is only available for requests from the local machine.

SOAP 1.1

The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values.

POST /pg/api12.asmx HTTP/1.1
Host: www.payrollservers.us
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://mc2cs.com/UpdateEmployeeFields"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <UpdateEmployeeFields xmlns="http://mc2cs.com/">
      <sessionID>string</sessionID>
      <ApplicationID>string</ApplicationID>
      <AddIfNotFound>boolean</AddIfNotFound>
      <IdentityField>EMPLOYEECODE or UNIQUEID</IdentityField>
      <Employees>
        <EmployeeFieldsToUpdate>
          <FieldsToUpdate>
            <FieldToUpdate xsi:nil="true" />
            <FieldToUpdate xsi:nil="true" />
          </FieldsToUpdate>
          <Identifier>string</Identifier>
          <OptionalSecondaryIdentifier>string</OptionalSecondaryIdentifier>
        </EmployeeFieldsToUpdate>
        <EmployeeFieldsToUpdate>
          <FieldsToUpdate>
            <FieldToUpdate xsi:nil="true" />
            <FieldToUpdate xsi:nil="true" />
          </FieldsToUpdate>
          <Identifier>string</Identifier>
          <OptionalSecondaryIdentifier>string</OptionalSecondaryIdentifier>
        </EmployeeFieldsToUpdate>
      </Employees>
      <OptionalSecondaryIdentityField>NOTUSED or DEPARTMENT or LOCATION or SUPERVISOR</OptionalSecondaryIdentityField>
    </UpdateEmployeeFields>
  </soap:Body>
</soap:Envelope>

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <UpdateEmployeeFieldsResponse xmlns="http://mc2cs.com/">
      <UpdateEmployeeFieldsResult>
        <ValidationFailuresList>
          <EmployeeUpdateFailures>
            <FieldValidationFailures xsi:nil="true" />
            <Identifier>string</Identifier>
          </EmployeeUpdateFailures>
          <EmployeeUpdateFailures>
            <FieldValidationFailures xsi:nil="true" />
            <Identifier>string</Identifier>
          </EmployeeUpdateFailures>
        </ValidationFailuresList>
      </UpdateEmployeeFieldsResult>
    </UpdateEmployeeFieldsResponse>
  </soap:Body>
</soap:Envelope>

SOAP 1.2

The following is a sample SOAP 1.2 request and response. The placeholders shown need to be replaced with actual values.

POST /pg/api12.asmx HTTP/1.1
Host: www.payrollservers.us
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <UpdateEmployeeFields xmlns="http://mc2cs.com/">
      <sessionID>string</sessionID>
      <ApplicationID>string</ApplicationID>
      <AddIfNotFound>boolean</AddIfNotFound>
      <IdentityField>EMPLOYEECODE or UNIQUEID</IdentityField>
      <Employees>
        <EmployeeFieldsToUpdate>
          <FieldsToUpdate>
            <FieldToUpdate xsi:nil="true" />
            <FieldToUpdate xsi:nil="true" />
          </FieldsToUpdate>
          <Identifier>string</Identifier>
          <OptionalSecondaryIdentifier>string</OptionalSecondaryIdentifier>
        </EmployeeFieldsToUpdate>
        <EmployeeFieldsToUpdate>
          <FieldsToUpdate>
            <FieldToUpdate xsi:nil="true" />
            <FieldToUpdate xsi:nil="true" />
          </FieldsToUpdate>
          <Identifier>string</Identifier>
          <OptionalSecondaryIdentifier>string</OptionalSecondaryIdentifier>
        </EmployeeFieldsToUpdate>
      </Employees>
      <OptionalSecondaryIdentityField>NOTUSED or DEPARTMENT or LOCATION or SUPERVISOR</OptionalSecondaryIdentityField>
    </UpdateEmployeeFields>
  </soap12:Body>
</soap12:Envelope>

HTTP/1.1 200 OK
Content-Type: application/soap+xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <UpdateEmployeeFieldsResponse xmlns="http://mc2cs.com/">
      <UpdateEmployeeFieldsResult>
        <ValidationFailuresList>
          <EmployeeUpdateFailures>
            <FieldValidationFailures xsi:nil="true" />
            <Identifier>string</Identifier>
          </EmployeeUpdateFailures>
          <EmployeeUpdateFailures>
            <FieldValidationFailures xsi:nil="true" />
            <Identifier>string</Identifier>
          </EmployeeUpdateFailures>
        </ValidationFailuresList>
      </UpdateEmployeeFieldsResult>
    </UpdateEmployeeFieldsResponse>
  </soap12:Body>
</soap12:Envelope>