Wospee Core HR API

Version 0.1.0 OpenAPI 3.0.3

Base URL https://{host}/v0 — Not published yet; this is the address planned for the first release. host defaults to api.dp-wospee.com.

Base URL https://api.wpdpwharol.com/v0 — Test environment, with test data only. Its API accesses are separate from the production ones.

The REST API of the Wospee Core HR: the people of a tenant and the data around them. A tenant is one environment of a customer of the Wospee Digital Platform, usually a company; most customers have one. Every call goes through the same checks as the Wospee portal: who the user is, which tenant the call is for, and which functions the user has there.

Version 0, a preview. Every path starts with /v0. Until the first release the contract can still change, without notice and without a transition period. The first release will publish /v1.

Access

The API uses OAuth 2.0, in the client credentials flow, and nothing else: no user names and passwords. To call it you need an API access, which belongs to one of your users, a person or a service user. A person creates their own, up to five, in the Wospee Digital Platform under People › API accesses; for a service user, Wospee creates them. An API access has a client ID and a client secret. The secret is shown once, when the access is created: keep it safe, and if you lose it, generate a new one. To build and try an integration, ask for an API access on the test environment, https://api.wpdpwharol.com/v0, which holds test data only.

  1. Ask the token endpoint for a token, with the client ID and the client secret. You do not need to name a scope: the token gets the one of the API, https://api.dp-wospee.com/access.
  2. Send the token in the Authorization header of every call: Authorization: Bearer <token>.
  3. Reuse the token until it expires (expires_in, in seconds: a token lasts one hour), then ask for a new one. Do not ask for a token for every call, and share one among your processes.
POST /oauth/token HTTP/1.1
Host: api.dp-wospee.com
Authorization: Basic <base64 of client_id:client_secret>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
{
  "access_token": "eyJraWQiOiJ...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

The client ID and secret travel only in the Authorization header, as above, never in the body: without the header the answer is 400. An API access gets at most 10 tokens in 10 minutes (see Limits).

A call acts for the user of its API access, with the functions and the tenants that the roles of that user give for the API. When that is one tenant, the call does not name it; when it is more than one, the call names its tenant in the WDP-Tenant header, for example WDP-Tenant: TE0083, and without it the answer is 400 with the code tenant_required. An API access can have an end date, after which it stops working, and it can be switched off at any time.

Requests and responses

Bodies are JSON, in UTF-8. A URL carries only identifiers, codes and pages: names and any other personal data travel in the body, never in the URL, so a search is a POST.

The HTTP status says how the call went. A successful answer is the resource itself, with no wrapper around it:

{
  "person_id": "3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01",
  "family_name": "Bianchi",
  "given_name": "Giulia"
}
  • A creation answers 201 Created, with the address of the new resource in the Location header and the resource in the body.
  • A list answers an object with the rows of the page, items, and how many rows the whole search finds, total (see Lists).
  • Every answer, errors included, carries WDP-Request-Id, the identifier of the call: quote it when you report a problem. A successful answer also carries WDP-Time-Zone, the time zone of the caller (see Dates and times).

Headers

All the headers of the API in one place; the other sections explain them. Header names are not case-sensitive.

In the callWhenWhat it carries
Authorizationevery callBearer and the token; on the token endpoint, Basic and the client ID and secret (see Access)
Content-Typea call with a bodyapplication/json; on the token endpoint, application/x-www-form-urlencoded
WDP-Tenantonly when the user of the API access has more than one tenantthe code of the tenant of the call (see Access)
Idempotency-Keyevery call that creates a recorda random code for that creation, sent again only when the same request is repeated (see Creating a record)
If-Matchevery call that changes a recordthe ETag of the record as you read it (see Changing a record)
Preferwhen you want the instants in local time toolocal-times, or local-times="Europe/Rome" with an IANA time zone (see Dates and times)
In the answerWhenWhat it carries
WDP-Request-Idevery answer, errors includedthe identifier of the call: quote it when you report a problem
WDP-Time-Zoneevery successful answerthe time zone of the caller, an IANA name (see Dates and times)
Content-Typeevery answer with a bodyapplication/json; for an error, application/problem+json
Location201 Createdthe address of the new record
ETagan answer with a record that can be changedthe version of the record, to send back in If-Match
Preference-Appliedwhen the call sent Prefer and it was appliedthe preference applied (see Dates and times)
Deprecation, Sunset, Linkevery answer of a version that will be switched offwhen the version was deprecated, when it stops working and where to read about it: check them in every answer (see Versions)

Errors

An error is a problem as described by RFC 9457, with the media type application/problem+json, whether it comes from the Core HR or from the gateway in front of it. Besides title and status, it has these members:

  • code: a short word in English that names the error, such as invalid_page. Programs decide what to do from status and code. A code never changes meaning and is never reused, but new codes can appear: a program that does not know a code acts on the status.
  • detail: a sentence in English that says what is wrong and how to fix it, for the people who build and run the integration. It names fields and limits, never the values of the call. Its words can change: a program never tests it.
  • field: the key of the call that is wrong, when there is one.
  • requestId: the identifier of the call, the same as in the WDP-Request-Id header; quote it when you report a problem.

When some fields of the body are not valid, the answer lists all of them at once in errors, one item per field, each with its own field, code and detail:

{
  "title": "Bad Request",
  "status": 400,
  "code": "invalid_fields",
  "detail": "Some fields are not valid: see errors.",
  "errors": [
    {
      "field": "family_name",
      "code": "required",
      "detail": "family_name is required."
    },
    {
      "field": "birth_date",
      "code": "invalid_date",
      "detail": "birth_date must be a date, YYYY-MM-DD."
    }
  ],
  "requestId": "6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60"
}
StatuscodeWhen
400invalid_fieldssome fields of the body are not valid: errors lists them
400bad_request, or a more precise code such as invalid_page or tenant_requireda value of the call is wrong: field names it
400idempotency_key_requireda call that creates a record needs the Idempotency-Key header
401unauthorizedthe token is missing, expired or not valid: ask for a new one
403access_disabledthe API access has been switched off
403access_expiredthe API access is past its end date
403forbiddenthe user may not make this call for this tenant
403read_onlythe call writes, and the user may only read here: with this function, or with the API
403blockedthe firewall blocked the request
404not_foundthe object does not exist for this tenant
404unknown_routethe path does not exist
409already_existsanother record of the tenant already has one of the codes you sent: existing_id names it
409request_in_progressa request with the same Idempotency-Key is still running
412record_changedthe record changed after you read it: read it again
422idempotency_key_reusedthe Idempotency-Key was already used for a different request
428if_match_requireda call that changes a record needs the If-Match header
429too_many_requeststoo many calls: wait, then try again
429too_many_tokensthe API access asked for more than 10 tokens in 10 minutes: reuse the token you have
500internal_erroran error on our side: quote the requestId
504timeoutthe call took too long

Only after a 401 can a new token help. An API access that is switched off or past its end date answers 403, because asking for new tokens does not change it.

Dates and times

  • A date is a day of the calendar, YYYY-MM-DD, for example a date of birth: 1985-04-23. It has no time zone and is never converted.
  • An instant is in UTC, in the RFC 3339 format with Z, for example when a record was changed: 2026-11-13T09:15:00.123Z.
  • A time of day of a work schedule, HH:MM:SS, is the local time of the workplace and is never converted.
  • Every successful answer carries, in the WDP-Time-Zone header, the time zone of the caller as an IANA name: the one of the user on that tenant, otherwise the one of the tenant, otherwise Europe/Rome. Use it to show an instant in local time.
  • A call may ask for the local time ready to show, with the Prefer header (RFC 7240): every instant then has a twin field whose name ends in _local, with the offset. Prefer: local-times gives them in the time zone of the caller; Prefer: local-times="America/New_York" gives them in the time zone named, which is always an IANA name, never an offset. The answer confirms it in Preference-Applied. A time zone that is not valid is ignored, as RFC 7240 wants: the answer then has no _local fields and no Preference-Applied.
  • Dates and times of day never change, with or without Prefer.
  • When you write, an instant always has Z or an offset. The _local fields are read-only and are ignored.

For example, for a record with an instant created_at:

GET /v0/people/3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01 HTTP/1.1
Authorization: Bearer eyJraWQiOiJ...
Prefer: local-times="America/New_York"
HTTP/1.1 200 OK
Preference-Applied: local-times="America/New_York"

{ "created_at": "2026-11-13T09:15:00.123Z", "created_at_local": "2026-11-13T04:15:00.123-05:00" }

Lists

A list answers one page at a time: 25 rows unless the call asks for another size, at most 100. A search sends search, filters, sort and page in its body, and the answer carries items, the rows of the page, and total, how many rows the whole search finds.

{
  "search": "giulia bianchi",
  "filters": {
    "family_name": "bia"
  },
  "sort": [
    {
      "by": "family_name",
      "direction": "asc"
    }
  ],
  "page": {
    "index": 0,
    "size": 25
  }
}
{
  "items": [
    {
      "person_id": "3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01",
      "family_name": "Bianchi",
      "given_name": "Giulia"
    }
  ],
  "total": 1
}

page.index starts from 0. With more than one word in search, every word must be found in one of the searchable fields, in any order: «giulia bianchi» finds Bianchi Giulia.

Limits

  • Ask for a token once and reuse it until it expires (see Access). An API access gets at most 10 tokens in 10 minutes: beyond that, the token endpoint answers 429 with the code too_many_tokens until the count goes down, so keep the token you have.
  • Spread your scheduled jobs: start them at a random minute, not on the hour, when every other job starts too.
  • When the API is busy, the answer is 429 with the code too_many_requests: wait a few seconds and try again, waiting a little longer at every new attempt.
  • Too many requests from the same IP address in a few minutes are blocked for a while: the answer is 403 with the code blocked.
  • A list answers at most 100 rows per page, and a person has at most five API accesses.

Versions

  • The version is in the path: /v0, then /v1.
  • Within a version the API only grows: new fields in answers, new optional parameters, new calls, new error codes. A client ignores what it does not know.
  • A change that can break a client gets a new version: a field removed or renamed, a type or a meaning changed, a parameter that becomes required.
  • When a new version comes out, the previous one keeps working for at least six months. From that day its answers carry three headers: Deprecation (RFC 9745), since when the version is deprecated; Sunset (RFC 8594), when it stops working; and Link, with rel="deprecation", the address of its notes on this page: what changes and how to move. A deprecated version that no API access uses any more can be switched off before its Sunset.
  • /v0 is a preview: it can change without notice, and it is switched off when /v1 comes out.

Watch the headers of every answer, not only this page: Deprecation and Sunset tell your software, from the first answer, that its version is going away. When they appear, log a warning with the Sunset date, where the people who run the integration will see it, and plan the move to the new version before that date.

HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT

Deprecation is a date written as @ and the seconds since 1 January 1970, UTC: here 1 January

  1. Sunset is an HTTP date.

Creating a record

Every call that creates a record needs the Idempotency-Key header: a random code that your software generates for that creation, for example a UUID, and sends again, unchanged, only when it repeats the same request. A search is not a creation and does not need it.

  • A repeat with the same key and the same request, within 24 hours, gets the first answer back, and nothing is created twice. Keys belong to the API access that sent them.
  • The same key with a different request is refused with 422 and the code idempotency_key_reused; a repeat that arrives while the first request is still running gets 409 and the code request_in_progress.
  • Without the header, the answer is 400 with the code idempotency_key_required.

A creation can also name the codes of the record in other systems, such as the employee number of a payroll system. When one of them already belongs to another record of the tenant, the answer is 409 with the code already_exists, and existing_id names that record.

Changing a record

A record that can be changed carries its version in the ETag header of the answer. A call that changes the record sends that version back in the If-Match header. When the record has changed in the meantime, the answer is 412 with the code record_changed: read the record again, then decide. A change without If-Match is refused with 428 and the code if_match_required. No call of this version changes a record yet: the rule applies from the first one.

Open points

To be decided before the first release:

  • the address of the API, https://api.dp-wospee.com/v0 for now;
  • the type of every error, which will point to its explanation on this page, at https://developers.dp-wospee.com/core-hr/.

Authentication

OAuth 2.0

OAuth 2.0 in the client credentials flow (RFC 6749, section 4.4), with the client ID and the client secret of an API access. The token goes in the Authorization header of every call, and is reused until it expires.

FlowAddressScopes
Client credentialsToken: https://api.dp-wospee.com/oauth/tokenhttps://api.dp-wospee.com/access — Call the public API. Every API access has it; a token request does not need to name it.

People

A person of a tenant, with the personal data that do not depend on employment: names, birth, citizenship, language. Employment, contracts and assignments are separate domains, which will follow.

Read a person

GET /people/{person_id}

Reads one person of the tenant of the call. The record has the fields that the tenant shows: a field hidden by its configuration is not in the answer.

Authentication: OAuth 2.0

Request

ParameterInTypeDescription
person_id requiredpathstring · uuid

The identifier of the person, as the Core HR gives it. It is opaque: use it as it is, without reading anything into it.

Example 3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01.

WDP-Tenantheaderstring

The tenant of the call. Send it only when the user of the API access works on more than one tenant; otherwise leave it out.

At most 50 characters. Example TE0083.

Responses

200 The record of the person.
HeaderTypeDescription
WDP-Request-Idstring

The identifier of the call in our logs. Quote it when you report a problem.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

WDP-Time-Zonestring

The time zone of the caller, as an IANA name.

Example Europe/Rome.

Body: application/json

FieldTypeDescription
person_id requiredstring · uuid

The identifier of the person in the Core HR, given at creation. It is opaque.

Example 3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01.

family_name requiredstring

Family name.

At most 255 characters. Example Bianchi.

second_family_namestring

Second family name, as used in Spain.

Can be null. At most 255 characters.

given_name requiredstring

Given name.

At most 255 characters. Example Giulia.

middle_namestring

Middle name.

Can be null. At most 255 characters.

preferred_namestring

The name the person likes to be called by.

Can be null. At most 255 characters.

titlestring

Courtesy title.

Can be null. At most 255 characters.

birth_datestring · date

Date of birth.

Can be null. Example 1985-04-23.

birth_countrystring

Country of birth, as an ISO 3166-1 alpha-2 code.

Can be null. Exactly 2 characters. Example IT.

birth_provincestring

Province of birth, as a code; for Italy, the two-letter abbreviation.

Can be null. At most 10 characters. Example MI.

citizenshipsstring

Citizenship, as an ISO 3166-1 alpha-2 code.

Can be null. At most 255 characters. Example IT.

preferred_languagestring

Preferred language, as an ISO 639-1 code.

Can be null. At most 10 characters. Example it.

status requiredstring

State of the record, active for a person in use; a person can also be archived or anonymized.

Example active.

source_system requiredstring

The system the person comes from: core_hr_wospee for a person entered in the Core HR, otherwise the system that sends it, for example cezanne.

At most 30 characters. Example core_hr_wospee.

Example

{
  "person_id": "3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01",
  "family_name": "Bianchi",
  "second_family_name": null,
  "given_name": "Giulia",
  "middle_name": null,
  "preferred_name": null,
  "title": null,
  "birth_date": "1985-04-23",
  "birth_country": "IT",
  "birth_province": "MI",
  "citizenships": "IT",
  "preferred_language": "it",
  "status": "active",
  "source_system": "core_hr_wospee"
}
400 A value of the call is wrong.

When some fields of the body are not valid, errors lists all of them; otherwise field names the value that is wrong.

HeaderTypeDescription
WDP-Request-Idstring

The identifier of the call in our logs. Quote it when you report a problem.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Body: application/problem+json

FieldTypeDescription
typestring

Always about:blank, the default of RFC 9457, until an error has a page of its own.

Example about:blank.

title requiredstring

The HTTP status in words.

Example Not Found.

status requiredinteger

The HTTP status.

Example 404.

code requiredstring

The short word that names the error. It never changes meaning and is never reused; new codes can appear, and a program that does not know one acts on the status.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example not_found.

detail requiredstring

What is wrong and how to fix it, in English, for people. It names fields and limits, never the values of the call. Its words can change: a program never tests it.

Example The object does not exist for this tenant..

fieldstring

The key of the call that is wrong, when there is one. A name, never a value.

Example person_id.

errorsarray of object (FieldProblem)

With the code invalid_fields, every field of the body that is not valid.

errors[].field requiredstring

The key of the field, with dots for nested fields. A name, never a value.

Example birth_date.

errors[].code requiredstring

The short word that names the problem of the field.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example invalid_date.

errors[].detail requiredstring

What is wrong with the field and how to fix it, in English. Never the value sent.

Example birth_date must be a date, YYYY-MM-DD..

existing_idstring

With the code already_exists, the identifier of the record that already exists.

Example 3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01.

requestIdstring

The identifier of the call in our logs.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Example

{
  "title": "Bad Request",
  "status": 400,
  "code": "invalid_fields",
  "detail": "Some fields are not valid: see errors.",
  "errors": [
    {
      "field": "family_name",
      "code": "required",
      "detail": "family_name is required."
    },
    {
      "field": "birth_date",
      "code": "invalid_date",
      "detail": "birth_date must be a date, YYYY-MM-DD."
    }
  ],
  "requestId": "6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60"
}
401 The token is missing, expired or not valid.

The gateway answers, before the call reaches the Core HR. Ask for a new token.

HeaderTypeDescription
WDP-Request-Idstring

The identifier of the call in our logs. Quote it when you report a problem.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Body: application/problem+json

FieldTypeDescription
typestring

Always about:blank, the default of RFC 9457, until an error has a page of its own.

Example about:blank.

title requiredstring

The HTTP status in words.

Example Not Found.

status requiredinteger

The HTTP status.

Example 404.

code requiredstring

The short word that names the error. It never changes meaning and is never reused; new codes can appear, and a program that does not know one acts on the status.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example not_found.

detail requiredstring

What is wrong and how to fix it, in English, for people. It names fields and limits, never the values of the call. Its words can change: a program never tests it.

Example The object does not exist for this tenant..

fieldstring

The key of the call that is wrong, when there is one. A name, never a value.

Example person_id.

errorsarray of object (FieldProblem)

With the code invalid_fields, every field of the body that is not valid.

errors[].field requiredstring

The key of the field, with dots for nested fields. A name, never a value.

Example birth_date.

errors[].code requiredstring

The short word that names the problem of the field.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example invalid_date.

errors[].detail requiredstring

What is wrong with the field and how to fix it, in English. Never the value sent.

Example birth_date must be a date, YYYY-MM-DD..

existing_idstring

With the code already_exists, the identifier of the record that already exists.

Example 3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01.

requestIdstring

The identifier of the call in our logs.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Example

{
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "The token is missing, expired or not valid: ask for a new one.",
  "requestId": "6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60"
}
403 The call is not allowed.

The user may not make this call for this tenant (forbidden), may only read here (read_only), or the API access is switched off (access_disabled) or past its end date (access_expired).

HeaderTypeDescription
WDP-Request-Idstring

The identifier of the call in our logs. Quote it when you report a problem.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Body: application/problem+json

FieldTypeDescription
typestring

Always about:blank, the default of RFC 9457, until an error has a page of its own.

Example about:blank.

title requiredstring

The HTTP status in words.

Example Not Found.

status requiredinteger

The HTTP status.

Example 404.

code requiredstring

The short word that names the error. It never changes meaning and is never reused; new codes can appear, and a program that does not know one acts on the status.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example not_found.

detail requiredstring

What is wrong and how to fix it, in English, for people. It names fields and limits, never the values of the call. Its words can change: a program never tests it.

Example The object does not exist for this tenant..

fieldstring

The key of the call that is wrong, when there is one. A name, never a value.

Example person_id.

errorsarray of object (FieldProblem)

With the code invalid_fields, every field of the body that is not valid.

errors[].field requiredstring

The key of the field, with dots for nested fields. A name, never a value.

Example birth_date.

errors[].code requiredstring

The short word that names the problem of the field.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example invalid_date.

errors[].detail requiredstring

What is wrong with the field and how to fix it, in English. Never the value sent.

Example birth_date must be a date, YYYY-MM-DD..

existing_idstring

With the code already_exists, the identifier of the record that already exists.

Example 3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01.

requestIdstring

The identifier of the call in our logs.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Example

{
  "title": "Forbidden",
  "status": 403,
  "code": "forbidden",
  "detail": "Your user has no function that allows this call for this tenant.",
  "requestId": "6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60"
}
404 The object does not exist for this tenant.
HeaderTypeDescription
WDP-Request-Idstring

The identifier of the call in our logs. Quote it when you report a problem.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Body: application/problem+json

FieldTypeDescription
typestring

Always about:blank, the default of RFC 9457, until an error has a page of its own.

Example about:blank.

title requiredstring

The HTTP status in words.

Example Not Found.

status requiredinteger

The HTTP status.

Example 404.

code requiredstring

The short word that names the error. It never changes meaning and is never reused; new codes can appear, and a program that does not know one acts on the status.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example not_found.

detail requiredstring

What is wrong and how to fix it, in English, for people. It names fields and limits, never the values of the call. Its words can change: a program never tests it.

Example The object does not exist for this tenant..

fieldstring

The key of the call that is wrong, when there is one. A name, never a value.

Example person_id.

errorsarray of object (FieldProblem)

With the code invalid_fields, every field of the body that is not valid.

errors[].field requiredstring

The key of the field, with dots for nested fields. A name, never a value.

Example birth_date.

errors[].code requiredstring

The short word that names the problem of the field.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example invalid_date.

errors[].detail requiredstring

What is wrong with the field and how to fix it, in English. Never the value sent.

Example birth_date must be a date, YYYY-MM-DD..

existing_idstring

With the code already_exists, the identifier of the record that already exists.

Example 3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01.

requestIdstring

The identifier of the call in our logs.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Example

{
  "title": "Not Found",
  "status": 404,
  "code": "not_found",
  "detail": "The object does not exist for this tenant.",
  "requestId": "6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60"
}
500 An error on our side. Quote the requestId when you report it.
HeaderTypeDescription
WDP-Request-Idstring

The identifier of the call in our logs. Quote it when you report a problem.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Body: application/problem+json

FieldTypeDescription
typestring

Always about:blank, the default of RFC 9457, until an error has a page of its own.

Example about:blank.

title requiredstring

The HTTP status in words.

Example Not Found.

status requiredinteger

The HTTP status.

Example 404.

code requiredstring

The short word that names the error. It never changes meaning and is never reused; new codes can appear, and a program that does not know one acts on the status.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example not_found.

detail requiredstring

What is wrong and how to fix it, in English, for people. It names fields and limits, never the values of the call. Its words can change: a program never tests it.

Example The object does not exist for this tenant..

fieldstring

The key of the call that is wrong, when there is one. A name, never a value.

Example person_id.

errorsarray of object (FieldProblem)

With the code invalid_fields, every field of the body that is not valid.

errors[].field requiredstring

The key of the field, with dots for nested fields. A name, never a value.

Example birth_date.

errors[].code requiredstring

The short word that names the problem of the field.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example invalid_date.

errors[].detail requiredstring

What is wrong with the field and how to fix it, in English. Never the value sent.

Example birth_date must be a date, YYYY-MM-DD..

existing_idstring

With the code already_exists, the identifier of the record that already exists.

Example 3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01.

requestIdstring

The identifier of the call in our logs.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Example

{
  "title": "Internal Server Error",
  "status": 500,
  "code": "internal_error",
  "detail": "An error on our side. Quote the requestId when you report it.",
  "requestId": "6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60"
}

Create a person

POST /people

Creates a person for the tenant of the call. The answer is 201 Created, with the address of the person in Location and the new record, with its person_id, in the body. status starts as active and source_system is core_hr_wospee. The creation is written to the audit trail and published as an event.

Authentication: OAuth 2.0

Request

ParameterInTypeDescription
WDP-Tenantheaderstring

The tenant of the call. Send it only when the user of the API access works on more than one tenant; otherwise leave it out.

At most 50 characters. Example TE0083.

Idempotency-Key requiredheaderstring

A random code that your software generates for this creation, for example a UUID. Send it again, unchanged, only when you repeat the same request: within 24 hours the repeat gets the first answer back, and nothing is created twice.

At least 8 characters. At most 255 characters. Example 5b1e0c7a-2f4d-4a7e-9c0b-3e8f1a2d6c44.

Body, required: application/json

FieldTypeDescription
family_name requiredstring

Family name.

At most 255 characters. Example Bianchi.

second_family_namestring

Second family name, as used in Spain.

Can be null. At most 255 characters.

given_name requiredstring

Given name.

At most 255 characters. Example Giulia.

middle_namestring

Middle name.

Can be null. At most 255 characters.

preferred_namestring

The name the person likes to be called by.

Can be null. At most 255 characters.

titlestring

Courtesy title.

Can be null. At most 255 characters.

birth_datestring · date

Date of birth.

Can be null. Example 1985-04-23.

birth_countrystring

Country of birth, as an ISO 3166-1 alpha-2 code.

Can be null. Exactly 2 characters. Example IT.

birth_provincestring

Province of birth, as a code; for Italy, the two-letter abbreviation.

Can be null. At most 10 characters. Example MI.

citizenshipsstring

Citizenship, as an ISO 3166-1 alpha-2 code.

Can be null. At most 255 characters. Example IT.

preferred_languagestring

Preferred language, as an ISO 639-1 code.

Can be null. At most 10 characters. Example it.

external_identifiersarray of object (ExternalIdentifier)

Codes of the person in other systems, optional. When one of them already belongs to another person of the tenant, the creation is refused with 409 and already_exists.

external_identifiers[].system requiredstring

The other system, for example zucchetti or cezanne.

At most 50 characters. Example zucchetti.

external_identifiers[].type requiredstring

The kind of code in that system, for example employee_number.

At most 50 characters. Example employee_number.

external_identifiers[].value requiredstring

The code.

At most 255 characters. Example 00123.

Example

{
  "family_name": "Bianchi",
  "given_name": "Giulia",
  "birth_date": "1985-04-23",
  "birth_country": "IT",
  "birth_province": "MI",
  "citizenships": "IT",
  "preferred_language": "it",
  "external_identifiers": [
    {
      "system": "zucchetti",
      "type": "employee_number",
      "value": "00123"
    }
  ]
}

Responses

201 The person, created.
HeaderTypeDescription
Locationstring

The address of the new person.

Example /v0/people/3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01.

WDP-Request-Idstring

The identifier of the call in our logs. Quote it when you report a problem.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

WDP-Time-Zonestring

The time zone of the caller, as an IANA name.

Example Europe/Rome.

Body: application/json

FieldTypeDescription
person_id requiredstring · uuid

The identifier of the person in the Core HR, given at creation. It is opaque.

Example 3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01.

family_name requiredstring

Family name.

At most 255 characters. Example Bianchi.

second_family_namestring

Second family name, as used in Spain.

Can be null. At most 255 characters.

given_name requiredstring

Given name.

At most 255 characters. Example Giulia.

middle_namestring

Middle name.

Can be null. At most 255 characters.

preferred_namestring

The name the person likes to be called by.

Can be null. At most 255 characters.

titlestring

Courtesy title.

Can be null. At most 255 characters.

birth_datestring · date

Date of birth.

Can be null. Example 1985-04-23.

birth_countrystring

Country of birth, as an ISO 3166-1 alpha-2 code.

Can be null. Exactly 2 characters. Example IT.

birth_provincestring

Province of birth, as a code; for Italy, the two-letter abbreviation.

Can be null. At most 10 characters. Example MI.

citizenshipsstring

Citizenship, as an ISO 3166-1 alpha-2 code.

Can be null. At most 255 characters. Example IT.

preferred_languagestring

Preferred language, as an ISO 639-1 code.

Can be null. At most 10 characters. Example it.

status requiredstring

State of the record, active for a person in use; a person can also be archived or anonymized.

Example active.

source_system requiredstring

The system the person comes from: core_hr_wospee for a person entered in the Core HR, otherwise the system that sends it, for example cezanne.

At most 30 characters. Example core_hr_wospee.

Example

{
  "person_id": "3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01",
  "family_name": "Bianchi",
  "second_family_name": null,
  "given_name": "Giulia",
  "middle_name": null,
  "preferred_name": null,
  "title": null,
  "birth_date": "1985-04-23",
  "birth_country": "IT",
  "birth_province": "MI",
  "citizenships": "IT",
  "preferred_language": "it",
  "status": "active",
  "source_system": "core_hr_wospee"
}
400 A value of the call is wrong.

When some fields of the body are not valid, errors lists all of them; otherwise field names the value that is wrong.

HeaderTypeDescription
WDP-Request-Idstring

The identifier of the call in our logs. Quote it when you report a problem.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Body: application/problem+json

FieldTypeDescription
typestring

Always about:blank, the default of RFC 9457, until an error has a page of its own.

Example about:blank.

title requiredstring

The HTTP status in words.

Example Not Found.

status requiredinteger

The HTTP status.

Example 404.

code requiredstring

The short word that names the error. It never changes meaning and is never reused; new codes can appear, and a program that does not know one acts on the status.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example not_found.

detail requiredstring

What is wrong and how to fix it, in English, for people. It names fields and limits, never the values of the call. Its words can change: a program never tests it.

Example The object does not exist for this tenant..

fieldstring

The key of the call that is wrong, when there is one. A name, never a value.

Example person_id.

errorsarray of object (FieldProblem)

With the code invalid_fields, every field of the body that is not valid.

errors[].field requiredstring

The key of the field, with dots for nested fields. A name, never a value.

Example birth_date.

errors[].code requiredstring

The short word that names the problem of the field.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example invalid_date.

errors[].detail requiredstring

What is wrong with the field and how to fix it, in English. Never the value sent.

Example birth_date must be a date, YYYY-MM-DD..

existing_idstring

With the code already_exists, the identifier of the record that already exists.

Example 3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01.

requestIdstring

The identifier of the call in our logs.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Example

{
  "title": "Bad Request",
  "status": 400,
  "code": "invalid_fields",
  "detail": "Some fields are not valid: see errors.",
  "errors": [
    {
      "field": "family_name",
      "code": "required",
      "detail": "family_name is required."
    },
    {
      "field": "birth_date",
      "code": "invalid_date",
      "detail": "birth_date must be a date, YYYY-MM-DD."
    }
  ],
  "requestId": "6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60"
}
401 The token is missing, expired or not valid.

The gateway answers, before the call reaches the Core HR. Ask for a new token.

HeaderTypeDescription
WDP-Request-Idstring

The identifier of the call in our logs. Quote it when you report a problem.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Body: application/problem+json

FieldTypeDescription
typestring

Always about:blank, the default of RFC 9457, until an error has a page of its own.

Example about:blank.

title requiredstring

The HTTP status in words.

Example Not Found.

status requiredinteger

The HTTP status.

Example 404.

code requiredstring

The short word that names the error. It never changes meaning and is never reused; new codes can appear, and a program that does not know one acts on the status.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example not_found.

detail requiredstring

What is wrong and how to fix it, in English, for people. It names fields and limits, never the values of the call. Its words can change: a program never tests it.

Example The object does not exist for this tenant..

fieldstring

The key of the call that is wrong, when there is one. A name, never a value.

Example person_id.

errorsarray of object (FieldProblem)

With the code invalid_fields, every field of the body that is not valid.

errors[].field requiredstring

The key of the field, with dots for nested fields. A name, never a value.

Example birth_date.

errors[].code requiredstring

The short word that names the problem of the field.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example invalid_date.

errors[].detail requiredstring

What is wrong with the field and how to fix it, in English. Never the value sent.

Example birth_date must be a date, YYYY-MM-DD..

existing_idstring

With the code already_exists, the identifier of the record that already exists.

Example 3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01.

requestIdstring

The identifier of the call in our logs.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Example

{
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "The token is missing, expired or not valid: ask for a new one.",
  "requestId": "6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60"
}
403 The call is not allowed.

The user may not make this call for this tenant (forbidden), may only read here (read_only), or the API access is switched off (access_disabled) or past its end date (access_expired).

HeaderTypeDescription
WDP-Request-Idstring

The identifier of the call in our logs. Quote it when you report a problem.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Body: application/problem+json

FieldTypeDescription
typestring

Always about:blank, the default of RFC 9457, until an error has a page of its own.

Example about:blank.

title requiredstring

The HTTP status in words.

Example Not Found.

status requiredinteger

The HTTP status.

Example 404.

code requiredstring

The short word that names the error. It never changes meaning and is never reused; new codes can appear, and a program that does not know one acts on the status.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example not_found.

detail requiredstring

What is wrong and how to fix it, in English, for people. It names fields and limits, never the values of the call. Its words can change: a program never tests it.

Example The object does not exist for this tenant..

fieldstring

The key of the call that is wrong, when there is one. A name, never a value.

Example person_id.

errorsarray of object (FieldProblem)

With the code invalid_fields, every field of the body that is not valid.

errors[].field requiredstring

The key of the field, with dots for nested fields. A name, never a value.

Example birth_date.

errors[].code requiredstring

The short word that names the problem of the field.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example invalid_date.

errors[].detail requiredstring

What is wrong with the field and how to fix it, in English. Never the value sent.

Example birth_date must be a date, YYYY-MM-DD..

existing_idstring

With the code already_exists, the identifier of the record that already exists.

Example 3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01.

requestIdstring

The identifier of the call in our logs.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Example

{
  "title": "Forbidden",
  "status": 403,
  "code": "forbidden",
  "detail": "Your user has no function that allows this call for this tenant.",
  "requestId": "6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60"
}
409 The creation clashes with something that exists.

Another record of the tenant already has one of the codes you sent (already_exists, and existing_id names it), or a request with the same Idempotency-Key is still running (request_in_progress).

HeaderTypeDescription
WDP-Request-Idstring

The identifier of the call in our logs. Quote it when you report a problem.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Body: application/problem+json

FieldTypeDescription
typestring

Always about:blank, the default of RFC 9457, until an error has a page of its own.

Example about:blank.

title requiredstring

The HTTP status in words.

Example Not Found.

status requiredinteger

The HTTP status.

Example 404.

code requiredstring

The short word that names the error. It never changes meaning and is never reused; new codes can appear, and a program that does not know one acts on the status.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example not_found.

detail requiredstring

What is wrong and how to fix it, in English, for people. It names fields and limits, never the values of the call. Its words can change: a program never tests it.

Example The object does not exist for this tenant..

fieldstring

The key of the call that is wrong, when there is one. A name, never a value.

Example person_id.

errorsarray of object (FieldProblem)

With the code invalid_fields, every field of the body that is not valid.

errors[].field requiredstring

The key of the field, with dots for nested fields. A name, never a value.

Example birth_date.

errors[].code requiredstring

The short word that names the problem of the field.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example invalid_date.

errors[].detail requiredstring

What is wrong with the field and how to fix it, in English. Never the value sent.

Example birth_date must be a date, YYYY-MM-DD..

existing_idstring

With the code already_exists, the identifier of the record that already exists.

Example 3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01.

requestIdstring

The identifier of the call in our logs.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Example

{
  "title": "Conflict",
  "status": 409,
  "code": "already_exists",
  "detail": "Another person of the tenant already has this code; existing_id names it.",
  "existing_id": "3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01",
  "requestId": "6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60"
}
422 The Idempotency-Key was already used for a different request.
HeaderTypeDescription
WDP-Request-Idstring

The identifier of the call in our logs. Quote it when you report a problem.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Body: application/problem+json

FieldTypeDescription
typestring

Always about:blank, the default of RFC 9457, until an error has a page of its own.

Example about:blank.

title requiredstring

The HTTP status in words.

Example Not Found.

status requiredinteger

The HTTP status.

Example 404.

code requiredstring

The short word that names the error. It never changes meaning and is never reused; new codes can appear, and a program that does not know one acts on the status.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example not_found.

detail requiredstring

What is wrong and how to fix it, in English, for people. It names fields and limits, never the values of the call. Its words can change: a program never tests it.

Example The object does not exist for this tenant..

fieldstring

The key of the call that is wrong, when there is one. A name, never a value.

Example person_id.

errorsarray of object (FieldProblem)

With the code invalid_fields, every field of the body that is not valid.

errors[].field requiredstring

The key of the field, with dots for nested fields. A name, never a value.

Example birth_date.

errors[].code requiredstring

The short word that names the problem of the field.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example invalid_date.

errors[].detail requiredstring

What is wrong with the field and how to fix it, in English. Never the value sent.

Example birth_date must be a date, YYYY-MM-DD..

existing_idstring

With the code already_exists, the identifier of the record that already exists.

Example 3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01.

requestIdstring

The identifier of the call in our logs.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Example

{
  "title": "Unprocessable Content",
  "status": 422,
  "code": "idempotency_key_reused",
  "detail": "This Idempotency-Key was already used for a different request. Generate a new one.",
  "requestId": "6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60"
}
500 An error on our side. Quote the requestId when you report it.
HeaderTypeDescription
WDP-Request-Idstring

The identifier of the call in our logs. Quote it when you report a problem.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Body: application/problem+json

FieldTypeDescription
typestring

Always about:blank, the default of RFC 9457, until an error has a page of its own.

Example about:blank.

title requiredstring

The HTTP status in words.

Example Not Found.

status requiredinteger

The HTTP status.

Example 404.

code requiredstring

The short word that names the error. It never changes meaning and is never reused; new codes can appear, and a program that does not know one acts on the status.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example not_found.

detail requiredstring

What is wrong and how to fix it, in English, for people. It names fields and limits, never the values of the call. Its words can change: a program never tests it.

Example The object does not exist for this tenant..

fieldstring

The key of the call that is wrong, when there is one. A name, never a value.

Example person_id.

errorsarray of object (FieldProblem)

With the code invalid_fields, every field of the body that is not valid.

errors[].field requiredstring

The key of the field, with dots for nested fields. A name, never a value.

Example birth_date.

errors[].code requiredstring

The short word that names the problem of the field.

Pattern ^[a-z][a-z0-9_]{0,49}$. Example invalid_date.

errors[].detail requiredstring

What is wrong with the field and how to fix it, in English. Never the value sent.

Example birth_date must be a date, YYYY-MM-DD..

existing_idstring

With the code already_exists, the identifier of the record that already exists.

Example 3f6c1e2a-8b4d-4c3e-9a1f-2d7e5b8c9a01.

requestIdstring

The identifier of the call in our logs.

Example 6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60.

Example

{
  "title": "Internal Server Error",
  "status": 500,
  "code": "internal_error",
  "detail": "An error on our side. Quote the requestId when you report it.",
  "requestId": "6f1c2d9e-1b7a-4c1e-9f0e-1d2c3b4a5f60"
}