CreateEmployee

Organisation service 1.9: Creates an employee - INACTIVE, Standard licence, no password and no roles beyond the personal one; activation and welcome mail are separate calls.


Service	Organisation 1.9
Endpoint	`POST https://app{server-number}.timelog.com/{account}/WebServices/Organisation/V1_9/OrganisationServiceSecure.svc`
SOAPAction	`http://www.timelog.com/api/tlp/v1_9/OrganisationService/CreateEmployee`
Content-Type	`text/xml; charset=utf-8`
Authentication	A token from GetToken
Permissions	The caller needs an Employee-area privilege - all employees, employees in my legal entity, or employees in my department and sub-departments - covering the TARGET employee AS MODIFIED, plus the Create or Edit action on it; otherwise the save is refused.
Changes data	Yes
Safe to retry	Depends on the call

How it works

Builds a new user from the parameters, resolving working time, holiday calendar, allowance legislation, employee type, cost price and hourly rate BY NAME and the department by GUID, and saves it. Fixed by the server: licence Standard, the system salary group, the default legal entity, server time zone, language English, employment date = now. The employee is created INACTIVE - call ActivateEmployee. No password is set and no e-mail is sent: the employee sets a password through the link CreateEmployeeNotification e-mails. User name and initials must not clash with ANY existing user, active or inactive. The response is the unsaved object: EmployeeID is 0.

Parameters

Each parameter has one label: Required, Conditional (required depending on other values) or Optional. Send them in the order shown.

employeeGuidguid

Required

GUID for the new employee, stored as sent - generate a new one per employee. It becomes EmployeeHeader.ID.

usernamestring

Optional. Login user name. Blank -> not set. Must not be used by ANY other user, active or inactive.

initialsstring

Required

Initials; blank -> 'No initials was provided'. Must not be used by any other user.

firstnamestring

Required

Blank -> 'No first name was provided'.

lastnamestring

Required

Blank -> 'No last name was provided'.

employeeNostring

Optional.

emailstring

Required

CreateEmployeeNotification sends the set-password link here.

titlestring

Optional. Job title.

telephonestring

Optional. Telephone number.

mobilestring

Optional. Mobile number.

normalWorkingTimeNamestring

Required

holidayCalendarNamestring

Required

NAME of a public-holiday calendar; not found -> 'The holiday calendar was not found'.

allowanceLegislationNamestring

Required

Allowance legislation name; not found -> 'The allowance settings was not found'.

employeeTypeNamestring

Required

NAME of an employee type; not found -> 'The employee type was not found'.

hourlyRateNamestring

Required

NAME of a standard hourly rate of the DEFAULT legal entity; not found -> 'The hourly rate was not found'.

costPriceNamestring

Required

NAME of a cost price of the DEFAULT legal entity; not found -> 'The cost price was not found'.

externalIdentifierstring

Optional. Free external identifier.

departmentGuidguid

Required

GUID of the department; not found -> 'The department is not found'. The caller's employee privilege must cover this department.

tokenSecurityToken

Required

The token from GetToken: Initials, Expires and Hash, sent back unchanged.

Request

POST /{account}/WebServices/Organisation/V1_9/OrganisationServiceSecure.svc HTTP/1.1
Host: app{server-number}.timelog.com
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://www.timelog.com/api/tlp/v1_9/OrganisationService/CreateEmployee"

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:org="http://www.timelog.com/api/tlp/v1_9"
                  xmlns:tok="http://www.timelog.com/api/tlp/v1_3">
  <soapenv:Body>
    <org:CreateEmployee>
      <org:employeeGuid>{employeeGuid}</org:employeeGuid>
      <org:username>{username}</org:username>
      <org:initials>{initials}</org:initials>
      <org:firstname>{firstname}</org:firstname>
      <org:lastname>{lastname}</org:lastname>
      <org:employeeNo>{employeeNo}</org:employeeNo>
      <org:email>{email}</org:email>
      <org:title>{title}</org:title>
      <org:telephone>{telephone}</org:telephone>
      <org:mobile>{mobile}</org:mobile>
      <org:normalWorkingTimeName>{normalWorkingTimeName}</org:normalWorkingTimeName>
      <org:holidayCalendarName>{holidayCalendarName}</org:holidayCalendarName>
      <org:allowanceLegislationName>{allowanceLegislationName}</org:allowanceLegislationName>
      <org:employeeTypeName>{employeeTypeName}</org:employeeTypeName>
      <org:hourlyRateName>{hourlyRateName}</org:hourlyRateName>
      <org:costPriceName>{costPriceName}</org:costPriceName>
      <org:externalIdentifier>{externalIdentifier}</org:externalIdentifier>
      <org:departmentGuid>{departmentGuid}</org:departmentGuid>
      <org:token>
        <tok:Initials>{Initials from GetToken}</tok:Initials>
        <tok:Expires>{Expires from GetToken, unchanged}</tok:Expires>
        <tok:Hash>{Hash from GetToken}</tok:Hash>
      </org:token>
    </org:CreateEmployee>
  </soapenv:Body>
</soapenv:Envelope>

curl -X POST "https://app{server-number}.timelog.com/{account}/WebServices/Organisation/V1_9/OrganisationServiceSecure.svc" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H 'SOAPAction: "http://www.timelog.com/api/tlp/v1_9/OrganisationService/CreateEmployee"' \
  --data-binary @request.xml

import requests

URL = "https://app{server-number}.timelog.com/{account}/WebServices/Organisation/V1_9/OrganisationServiceSecure.svc"
SOAP_ACTION = '"http://www.timelog.com/api/tlp/v1_9/OrganisationService/CreateEmployee"'

envelope = """<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:org="http://www.timelog.com/api/tlp/v1_9"
                  xmlns:tok="http://www.timelog.com/api/tlp/v1_3">
  <soapenv:Body>
    <org:CreateEmployee>
      <org:employeeGuid>{employeeGuid}</org:employeeGuid>
      <org:username>{username}</org:username>
      <org:initials>{initials}</org:initials>
      <org:firstname>{firstname}</org:firstname>
      <org:lastname>{lastname}</org:lastname>
      <org:employeeNo>{employeeNo}</org:employeeNo>
      <org:email>{email}</org:email>
      <org:title>{title}</org:title>
      <org:telephone>{telephone}</org:telephone>
      <org:mobile>{mobile}</org:mobile>
      <org:normalWorkingTimeName>{normalWorkingTimeName}</org:normalWorkingTimeName>
      <org:holidayCalendarName>{holidayCalendarName}</org:holidayCalendarName>
      <org:allowanceLegislationName>{allowanceLegislationName}</org:allowanceLegislationName>
      <org:employeeTypeName>{employeeTypeName}</org:employeeTypeName>
      <org:hourlyRateName>{hourlyRateName}</org:hourlyRateName>
      <org:costPriceName>{costPriceName}</org:costPriceName>
      <org:externalIdentifier>{externalIdentifier}</org:externalIdentifier>
      <org:departmentGuid>{departmentGuid}</org:departmentGuid>
      <org:token>
        <tok:Initials>{Initials from GetToken}</tok:Initials>
        <tok:Expires>{Expires from GetToken, unchanged}</tok:Expires>
        <tok:Hash>{Hash from GetToken}</tok:Hash>
      </org:token>
    </org:CreateEmployee>
  </soapenv:Body>
</soapenv:Envelope>"""

response = requests.post(
    URL,
    data=envelope.encode("utf-8"),
    headers={"Content-Type": "text/xml; charset=utf-8", "SOAPAction": SOAP_ACTION},
    timeout=60,
)
result = parse_result(response)  # see "Responses and errors"

Replace every {…} placeholder with your own value.

Response

The call returns the standard response envelope. Check ResponseState first: a failed call still returns HTTP 200.

ResponseStatestring

Required

Success, Invalid or Error.

ErrorCodeinteger

0 on success, otherwise the error code. See Errors.

ReturnEmployeeHeader[]

Response<EmployeeHeader> of the object as built - ID is your employeeGuid, EmployeeID is 0. Never - failure is an Error envelope with an empty Return.

Example response

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

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <CreateEmployeeResponse xmlns="http://www.timelog.com/api/tlp/v1_9">
      <CreateEmployeeResult xmlns:a="http://api.timelog.com"
                            xmlns:b="http://www.timelog.com/api/tlp/v1_9"
                            xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:Return>
          <b:EmployeeHeader>
            <b:ID>3f2504e0-4f89-41d3-9a0c-305000000001</b:ID>
            <b:EmployeeID>1001</b:EmployeeID>
            <b:UserName>Example user</b:UserName>
            <b:Initials>ABC</b:Initials>
            <b:FirstName>Example first</b:FirstName>
            <b:LastName>Example last</b:LastName>
            <b:EmployeeNo>1001</b:EmployeeNo>
            <b:Fullname>Example</b:Fullname>
          </b:EmployeeHeader>
        </a:Return>
        <a:ReturnTypeDescription>EmployeeHeader</a:ReturnTypeDescription>
        <a:Request>…</a:Request>
        <a:ResponseState>Success</a:ResponseState>
        <a:Messages>
          <a:APIMessage>
            <a:Message>Duration of call was 0,0421337 sec.</a:Message>
            <a:Severity>Message</a:Severity>
            <a:ErrorCode>0</a:ErrorCode>
          </a:APIMessage>
        </a:Messages>
        <a:ErrorCode>0</a:ErrorCode>
        <a:IsReturnPaged>false</a:IsReturnPaged>
        <a:TotalPageCount>0</a:TotalPageCount>
      </CreateEmployeeResult>
    </CreateEmployeeResponse>
  </s:Body>
</s:Envelope>

Illustrative example: built from the service description (WSDL) in the same format as a real response, with made-up values. The Request block is shortened.

Errors

All errors come back with HTTP 200: check ResponseState, ErrorCode and Messages. The errors every operation can return (expired or invalid token, API not enabled, HTTPS required, general errors) are listed once in Responses and errors.

Errors specific to this operation:

ResponseState	ErrorCode	Message	What it means	What to do
Error	40001	Error during call on TimeLog.API, Message 'The {normal working week \| holiday calendar \| allowance settings \| employee type \| cost price \| hourly rate} was not found' / 'The department is not found'	A working time, holiday calendar, allowance, employee type, cost price, hourly rate or department look-up failed.	—
Error	40001	Error during call on TimeLog.API, Message '{The email address is mandatory \| No first name was provided \| No last name was provided \| No initials was provided \| No user name was provided}'	email, firstname, lastname or initials blank.	Send the value.
Error	40001	Error during call on TimeLog.API, Message 'The title exceeds the maximum length of 50 characters'	V1_9 only: title longer than 50 characters.	Shorten the title to 50 characters.
Error	40001	Error during call on TimeLog.API, Message 'The user violates the Business Rules for users'	Save refused: missing employee create privilege, user name / initials already used, invalid e-mail or employee number, invalid references.	Check the integration user's employee privileges first; then uniqueness of initials / user name; then the referenced data.
Error	—	—	—	Always send the string parameter, even as an empty string.

Was this page helpful?