Reference
Collections
People
Personal information
Create a person

Create a person

Creates a new person.

Caution

Duplicate detection happens only when you send externalReferenceIdentifier. Without it no duplicate check is applied, so a retried request can silently create a second person. With it, a create whose identifier is already in use fails with 409 Conflict and nothing is written. Send it whenever your integration might retry a create.

Tip

Check the Swagger page for more technical information on the endpoints.

Endpoint details

POST
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people

Headers: Authorization: Bearer {token}, User-Agent: {agent} Scope: connector-protimeapi-people.write

Body properties

Field Type Required Writable Description
firstName string Yes Yes First name of the person. Maximum 100 characters.
lastName string Yes Yes Last name of the person. Maximum 100 characters.
email string No Yes Email address. Maximum 254 characters, validated as an email address when supplied.
telephone string No Yes Telephone number. Maximum 30 characters, validated as a phone number when supplied.
mobile string No Yes Mobile phone number. Maximum 30 characters, validated as a phone number when supplied.
address string No Yes Street address with the number. Maximum 200 characters.
postalCode string No Yes Postal code. Maximum 20 characters.
town string No Yes Town or city. Maximum 100 characters.
countryISOCode string No Yes ISO code of the country. Maximum 10 characters, validated as a country code.
nationalityISOCode string No Yes ISO code of the nationality. Maximum 10 characters, validated as a country code.
sex string No Yes Sex of the person (Unknown, Male, Female, Other).
birthDate string No Yes Birth date of the person (YYYY-MM-DD).
badgeNumber string No Yes Badge number of the person. Maximum 50 characters.
employeeNumber string No Yes Employee number of the person. Maximum 50 characters.
payGroup string No Yes Pay group of the person. Maximum 50 characters.
inServiceDate string Yes Yes Date when the person enters service (YYYY-MM-DD). Must be on or after 1900-01-01.
outOfServiceDate string No Yes Date when the person stops service (YYYY-MM-DD). Must be on or after inServiceDate.
externalReferenceIdentifier object No Yes A single key-value pair identifying the person in an external system. Also acts as the duplicate guard. See below.

External references

This endpoint is the exception on the people collection: it takes its reference from the request body, not from the externalReferences query parameter. An externalReferences query parameter sent to this endpoint has no effect.

Endpoint How a reference is supplied
POST /people The externalReferenceIdentifier body property, described below
PUT /people/{personReference} The ?externalReferences=(people,…) query parameter, to select the person to update
GET /people/{personReference} The ?externalReferences=(people,…) query parameter, to select the person to retrieve

External reference identifier

externalReferenceIdentifier holds exactly one key-value pair. The key is either a predefined reference (@badge-number, @employee-number) or a custom reference name of your choice; the value is the identifier the person carries in your system.

Key type What it does
Predefined Acts as a duplicate guard only. The value must equal the badgeNumber or employeeNumber sent in the same request, and nothing is stored — @badge-number and @employee-number always resolve from those two fields.
Custom Stores the pair as an external reference on the people collection. The new person can then be addressed as ?externalReferences=(people,yourReferenceName) on later requests.

Any key starting with @ is treated as predefined. For the people collection only @badge-number and @employee-number are valid; any other @ key is rejected.

Whichever key type you use, the request is rejected with a 409 when an existing person already carries the same reference, and the person is not created. Omitting the property skips this check entirely.

See the external references page for details.

Error responses

Status Condition
400 Validation failed (missing firstName, lastName or inServiceDate, invalid ISO code, invalid email or phone, value too long, outOfServiceDate before inServiceDate)
400 externalReferenceIdentifier is empty, holds more than one entry, or its predefined value does not match badgeNumber or employeeNumber
400 The key of externalReferenceIdentifier starts with @ but is not @badge-number or @employee-number
400 The predefined value of externalReferenceIdentifier matches more than one existing person
401 Missing or invalid access token, or insufficient scope
409 A person with the same external reference identifier already exists

Success response

201 Created with a Location header pointing to the new person. The response body is empty.

Examples

Create a person

POST
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@protime.com",
  "telephone": "+32 2 123 45 67",
  "mobile": "+32 472 12 34 56",
  "address": "Main Street 1",
  "postalCode": "1000",
  "town": "Brussels",
  "countryISOCode": "BE",
  "nationalityISOCode": "BE",
  "sex": "Male",
  "birthDate": "1985-05-20",
  "badgeNumber": "123456",
  "employeeNumber": "EMP1234",
  "payGroup": "Monthly",
  "inServiceDate": "2021-01-15"
}

Create a person with a custom external reference identifier

The pair is stored for the people collection, so the person can afterwards be addressed as ?externalReferences=(people,hr-system-id).

POST
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people

{
  "firstName": "John",
  "lastName": "Doe",
  "badgeNumber": "123456",
  "employeeNumber": "EMP1234",
  "inServiceDate": "2021-01-15",
  "externalReferenceIdentifier": {
    "hr-system-id": "HR-98765"
  }
}

Create a person with a predefined external reference identifier

The value of @employee-number must match the employeeNumber field. Nothing is stored: the entry only guarantees that no other person already uses employee number EMP5678.

POST
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/people

{
  "firstName": "Jane",
  "lastName": "Roe",
  "employeeNumber": "EMP5678",
  "inServiceDate": "2024-09-01",
  "externalReferenceIdentifier": {
    "@employee-number": "EMP5678"
  }
}

Related pages

WebhooksUpdate a person