Wospee Core HR API
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.
- 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. - Send the token in the
Authorizationheader of every call:Authorization: Bearer <token>. - 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 theLocationheader 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 carriesWDP-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 call | When | What it carries |
|---|---|---|
Authorization | every call | Bearer and the token; on the token endpoint, Basic and the client ID and secret (see Access) |
Content-Type | a call with a body | application/json; on the token endpoint, application/x-www-form-urlencoded |
WDP-Tenant | only when the user of the API access has more than one tenant | the code of the tenant of the call (see Access) |
Idempotency-Key | every call that creates a record | a random code for that creation, sent again only when the same request is repeated (see Creating a record) |
If-Match | every call that changes a record | the ETag of the record as you read it (see Changing a record) |
Prefer | when you want the instants in local time too | local-times, or local-times="Europe/Rome" with an IANA time zone (see Dates and times) |
| In the answer | When | What it carries |
|---|---|---|
WDP-Request-Id | every answer, errors included | the identifier of the call: quote it when you report a problem |
WDP-Time-Zone | every successful answer | the time zone of the caller, an IANA name (see Dates and times) |
Content-Type | every answer with a body | application/json; for an error, application/problem+json |
Location | 201 Created | the address of the new record |
ETag | an answer with a record that can be changed | the version of the record, to send back in If-Match |
Preference-Applied | when the call sent Prefer and it was applied | the preference applied (see Dates and times) |
Deprecation, Sunset, Link | every answer of a version that will be switched off | when 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 asinvalid_page. Programs decide what to do fromstatusandcode. A code never changes meaning and is never reused, but new codes can appear: a program that does not know a code acts on thestatus.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 theWDP-Request-Idheader; 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"
}
| Status | code | When |
|---|---|---|
| 400 | invalid_fields | some fields of the body are not valid: errors lists them |
| 400 | bad_request, or a more precise code such as invalid_page or tenant_required | a value of the call is wrong: field names it |
| 400 | idempotency_key_required | a call that creates a record needs the Idempotency-Key header |
| 401 | unauthorized | the token is missing, expired or not valid: ask for a new one |
| 403 | access_disabled | the API access has been switched off |
| 403 | access_expired | the API access is past its end date |
| 403 | forbidden | the user may not make this call for this tenant |
| 403 | read_only | the call writes, and the user may only read here: with this function, or with the API |
| 403 | blocked | the firewall blocked the request |
| 404 | not_found | the object does not exist for this tenant |
| 404 | unknown_route | the path does not exist |
| 409 | already_exists | another record of the tenant already has one of the codes you sent: existing_id names it |
| 409 | request_in_progress | a request with the same Idempotency-Key is still running |
| 412 | record_changed | the record changed after you read it: read it again |
| 422 | idempotency_key_reused | the Idempotency-Key was already used for a different request |
| 428 | if_match_required | a call that changes a record needs the If-Match header |
| 429 | too_many_requests | too many calls: wait, then try again |
| 429 | too_many_tokens | the API access asked for more than 10 tokens in 10 minutes: reuse the token you have |
| 500 | internal_error | an error on our side: quote the requestId |
| 504 | timeout | the 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-Zoneheader, the time zone of the caller as an IANA name: the one of the user on that tenant, otherwise the one of the tenant, otherwiseEurope/Rome. Use it to show an instant in local time. - A call may ask for the local time ready to show, with the
Preferheader (RFC 7240): every instant then has a twin field whose name ends in_local, with the offset.Prefer: local-timesgives 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 inPreference-Applied. A time zone that is not valid is ignored, as RFC 7240 wants: the answer then has no_localfields and noPreference-Applied. - Dates and times of day never change, with or without
Prefer. - When you write, an instant always has
Zor an offset. The_localfields 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
429with the codetoo_many_tokensuntil 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
429with the codetoo_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
403with the codeblocked. - 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; andLink, withrel="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 itsSunset. /v0is a preview: it can change without notice, and it is switched off when/v1comes 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
Sunsetis 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
422and the codeidempotency_key_reused; a repeat that arrives while the first request is still running gets409and the coderequest_in_progress. - Without the header, the answer is
400with the codeidempotency_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/v0for now; - the
typeof every error, which will point to its explanation on this page, athttps://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.
| Flow | Address | Scopes |
|---|---|---|
| Client credentials | Token: https://api.dp-wospee.com/oauth/token | https://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
| Parameter | In | Type | Description |
|---|---|---|---|
| person_id required | path | string · 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 |
| WDP-Tenant | header | string | 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 |
Responses
200 The record of the person.
| Header | Type | Description |
|---|---|---|
| WDP-Request-Id | string | The identifier of the call in our logs. Quote it when you report a problem. Example |
| WDP-Time-Zone | string | The time zone of the caller, as an IANA name. Example |
Body: application/json
| Field | Type | Description |
|---|---|---|
| person_id required | string · uuid | The identifier of the person in the Core HR, given at creation. It is opaque. Example |
| family_name required | string | Family name. At most 255 characters. Example |
| second_family_name | string | Second family name, as used in Spain. Can be |
| given_name required | string | Given name. At most 255 characters. Example |
| middle_name | string | Middle name. Can be |
| preferred_name | string | The name the person likes to be called by. Can be |
| title | string | Courtesy title. Can be |
| birth_date | string · date | Date of birth. Can be |
| birth_country | string | Country of birth, as an ISO 3166-1 alpha-2 code. Can be |
| birth_province | string | Province of birth, as a code; for Italy, the two-letter abbreviation. Can be |
| citizenships | string | Citizenship, as an ISO 3166-1 alpha-2 code. Can be |
| preferred_language | string | Preferred language, as an ISO 639-1 code. Can be |
| status required | string | State of the record, Example |
| source_system required | string | The system the person comes from: At most 30 characters. Example |
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.
| Header | Type | Description |
|---|---|---|
| WDP-Request-Id | string | The identifier of the call in our logs. Quote it when you report a problem. Example |
Body: application/problem+json
| Field | Type | Description |
|---|---|---|
| type | string | Always Example |
| title required | string | The HTTP status in words. Example |
| status required | integer | The HTTP status. Example |
| code required | string | 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 |
| detail required | string | 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 |
| field | string | The key of the call that is wrong, when there is one. A name, never a value. Example |
| errors | array of object (FieldProblem) | With the code |
| errors[].field required | string | The key of the field, with dots for nested fields. A name, never a value. Example |
| errors[].code required | string | The short word that names the problem of the field. Pattern |
| errors[].detail required | string | What is wrong with the field and how to fix it, in English. Never the value sent. Example |
| existing_id | string | With the code Example |
| requestId | string | The identifier of the call in our logs. Example |
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.
| Header | Type | Description |
|---|---|---|
| WDP-Request-Id | string | The identifier of the call in our logs. Quote it when you report a problem. Example |
Body: application/problem+json
| Field | Type | Description |
|---|---|---|
| type | string | Always Example |
| title required | string | The HTTP status in words. Example |
| status required | integer | The HTTP status. Example |
| code required | string | 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 |
| detail required | string | 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 |
| field | string | The key of the call that is wrong, when there is one. A name, never a value. Example |
| errors | array of object (FieldProblem) | With the code |
| errors[].field required | string | The key of the field, with dots for nested fields. A name, never a value. Example |
| errors[].code required | string | The short word that names the problem of the field. Pattern |
| errors[].detail required | string | What is wrong with the field and how to fix it, in English. Never the value sent. Example |
| existing_id | string | With the code Example |
| requestId | string | The identifier of the call in our logs. Example |
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).
| Header | Type | Description |
|---|---|---|
| WDP-Request-Id | string | The identifier of the call in our logs. Quote it when you report a problem. Example |
Body: application/problem+json
| Field | Type | Description |
|---|---|---|
| type | string | Always Example |
| title required | string | The HTTP status in words. Example |
| status required | integer | The HTTP status. Example |
| code required | string | 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 |
| detail required | string | 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 |
| field | string | The key of the call that is wrong, when there is one. A name, never a value. Example |
| errors | array of object (FieldProblem) | With the code |
| errors[].field required | string | The key of the field, with dots for nested fields. A name, never a value. Example |
| errors[].code required | string | The short word that names the problem of the field. Pattern |
| errors[].detail required | string | What is wrong with the field and how to fix it, in English. Never the value sent. Example |
| existing_id | string | With the code Example |
| requestId | string | The identifier of the call in our logs. Example |
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.
| Header | Type | Description |
|---|---|---|
| WDP-Request-Id | string | The identifier of the call in our logs. Quote it when you report a problem. Example |
Body: application/problem+json
| Field | Type | Description |
|---|---|---|
| type | string | Always Example |
| title required | string | The HTTP status in words. Example |
| status required | integer | The HTTP status. Example |
| code required | string | 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 |
| detail required | string | 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 |
| field | string | The key of the call that is wrong, when there is one. A name, never a value. Example |
| errors | array of object (FieldProblem) | With the code |
| errors[].field required | string | The key of the field, with dots for nested fields. A name, never a value. Example |
| errors[].code required | string | The short word that names the problem of the field. Pattern |
| errors[].detail required | string | What is wrong with the field and how to fix it, in English. Never the value sent. Example |
| existing_id | string | With the code Example |
| requestId | string | The identifier of the call in our logs. Example |
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.
| Header | Type | Description |
|---|---|---|
| WDP-Request-Id | string | The identifier of the call in our logs. Quote it when you report a problem. Example |
Body: application/problem+json
| Field | Type | Description |
|---|---|---|
| type | string | Always Example |
| title required | string | The HTTP status in words. Example |
| status required | integer | The HTTP status. Example |
| code required | string | 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 |
| detail required | string | 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 |
| field | string | The key of the call that is wrong, when there is one. A name, never a value. Example |
| errors | array of object (FieldProblem) | With the code |
| errors[].field required | string | The key of the field, with dots for nested fields. A name, never a value. Example |
| errors[].code required | string | The short word that names the problem of the field. Pattern |
| errors[].detail required | string | What is wrong with the field and how to fix it, in English. Never the value sent. Example |
| existing_id | string | With the code Example |
| requestId | string | The identifier of the call in our logs. Example |
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
| Parameter | In | Type | Description |
|---|---|---|---|
| WDP-Tenant | header | string | 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 |
| Idempotency-Key required | header | string | 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 |
Body, required: application/json
| Field | Type | Description |
|---|---|---|
| family_name required | string | Family name. At most 255 characters. Example |
| second_family_name | string | Second family name, as used in Spain. Can be |
| given_name required | string | Given name. At most 255 characters. Example |
| middle_name | string | Middle name. Can be |
| preferred_name | string | The name the person likes to be called by. Can be |
| title | string | Courtesy title. Can be |
| birth_date | string · date | Date of birth. Can be |
| birth_country | string | Country of birth, as an ISO 3166-1 alpha-2 code. Can be |
| birth_province | string | Province of birth, as a code; for Italy, the two-letter abbreviation. Can be |
| citizenships | string | Citizenship, as an ISO 3166-1 alpha-2 code. Can be |
| preferred_language | string | Preferred language, as an ISO 639-1 code. Can be |
| external_identifiers | array 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 |
| external_identifiers[].system required | string | The other system, for example At most 50 characters. Example |
| external_identifiers[].type required | string | The kind of code in that system, for example At most 50 characters. Example |
| external_identifiers[].value required | string | The code. At most 255 characters. Example |
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.
| Header | Type | Description |
|---|---|---|
| Location | string | The address of the new person. Example |
| WDP-Request-Id | string | The identifier of the call in our logs. Quote it when you report a problem. Example |
| WDP-Time-Zone | string | The time zone of the caller, as an IANA name. Example |
Body: application/json
| Field | Type | Description |
|---|---|---|
| person_id required | string · uuid | The identifier of the person in the Core HR, given at creation. It is opaque. Example |
| family_name required | string | Family name. At most 255 characters. Example |
| second_family_name | string | Second family name, as used in Spain. Can be |
| given_name required | string | Given name. At most 255 characters. Example |
| middle_name | string | Middle name. Can be |
| preferred_name | string | The name the person likes to be called by. Can be |
| title | string | Courtesy title. Can be |
| birth_date | string · date | Date of birth. Can be |
| birth_country | string | Country of birth, as an ISO 3166-1 alpha-2 code. Can be |
| birth_province | string | Province of birth, as a code; for Italy, the two-letter abbreviation. Can be |
| citizenships | string | Citizenship, as an ISO 3166-1 alpha-2 code. Can be |
| preferred_language | string | Preferred language, as an ISO 639-1 code. Can be |
| status required | string | State of the record, Example |
| source_system required | string | The system the person comes from: At most 30 characters. Example |
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.
| Header | Type | Description |
|---|---|---|
| WDP-Request-Id | string | The identifier of the call in our logs. Quote it when you report a problem. Example |
Body: application/problem+json
| Field | Type | Description |
|---|---|---|
| type | string | Always Example |
| title required | string | The HTTP status in words. Example |
| status required | integer | The HTTP status. Example |
| code required | string | 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 |
| detail required | string | 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 |
| field | string | The key of the call that is wrong, when there is one. A name, never a value. Example |
| errors | array of object (FieldProblem) | With the code |
| errors[].field required | string | The key of the field, with dots for nested fields. A name, never a value. Example |
| errors[].code required | string | The short word that names the problem of the field. Pattern |
| errors[].detail required | string | What is wrong with the field and how to fix it, in English. Never the value sent. Example |
| existing_id | string | With the code Example |
| requestId | string | The identifier of the call in our logs. Example |
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.
| Header | Type | Description |
|---|---|---|
| WDP-Request-Id | string | The identifier of the call in our logs. Quote it when you report a problem. Example |
Body: application/problem+json
| Field | Type | Description |
|---|---|---|
| type | string | Always Example |
| title required | string | The HTTP status in words. Example |
| status required | integer | The HTTP status. Example |
| code required | string | 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 |
| detail required | string | 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 |
| field | string | The key of the call that is wrong, when there is one. A name, never a value. Example |
| errors | array of object (FieldProblem) | With the code |
| errors[].field required | string | The key of the field, with dots for nested fields. A name, never a value. Example |
| errors[].code required | string | The short word that names the problem of the field. Pattern |
| errors[].detail required | string | What is wrong with the field and how to fix it, in English. Never the value sent. Example |
| existing_id | string | With the code Example |
| requestId | string | The identifier of the call in our logs. Example |
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).
| Header | Type | Description |
|---|---|---|
| WDP-Request-Id | string | The identifier of the call in our logs. Quote it when you report a problem. Example |
Body: application/problem+json
| Field | Type | Description |
|---|---|---|
| type | string | Always Example |
| title required | string | The HTTP status in words. Example |
| status required | integer | The HTTP status. Example |
| code required | string | 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 |
| detail required | string | 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 |
| field | string | The key of the call that is wrong, when there is one. A name, never a value. Example |
| errors | array of object (FieldProblem) | With the code |
| errors[].field required | string | The key of the field, with dots for nested fields. A name, never a value. Example |
| errors[].code required | string | The short word that names the problem of the field. Pattern |
| errors[].detail required | string | What is wrong with the field and how to fix it, in English. Never the value sent. Example |
| existing_id | string | With the code Example |
| requestId | string | The identifier of the call in our logs. Example |
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).
| Header | Type | Description |
|---|---|---|
| WDP-Request-Id | string | The identifier of the call in our logs. Quote it when you report a problem. Example |
Body: application/problem+json
| Field | Type | Description |
|---|---|---|
| type | string | Always Example |
| title required | string | The HTTP status in words. Example |
| status required | integer | The HTTP status. Example |
| code required | string | 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 |
| detail required | string | 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 |
| field | string | The key of the call that is wrong, when there is one. A name, never a value. Example |
| errors | array of object (FieldProblem) | With the code |
| errors[].field required | string | The key of the field, with dots for nested fields. A name, never a value. Example |
| errors[].code required | string | The short word that names the problem of the field. Pattern |
| errors[].detail required | string | What is wrong with the field and how to fix it, in English. Never the value sent. Example |
| existing_id | string | With the code Example |
| requestId | string | The identifier of the call in our logs. Example |
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.
| Header | Type | Description |
|---|---|---|
| WDP-Request-Id | string | The identifier of the call in our logs. Quote it when you report a problem. Example |
Body: application/problem+json
| Field | Type | Description |
|---|---|---|
| type | string | Always Example |
| title required | string | The HTTP status in words. Example |
| status required | integer | The HTTP status. Example |
| code required | string | 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 |
| detail required | string | 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 |
| field | string | The key of the call that is wrong, when there is one. A name, never a value. Example |
| errors | array of object (FieldProblem) | With the code |
| errors[].field required | string | The key of the field, with dots for nested fields. A name, never a value. Example |
| errors[].code required | string | The short word that names the problem of the field. Pattern |
| errors[].detail required | string | What is wrong with the field and how to fix it, in English. Never the value sent. Example |
| existing_id | string | With the code Example |
| requestId | string | The identifier of the call in our logs. Example |
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.
| Header | Type | Description |
|---|---|---|
| WDP-Request-Id | string | The identifier of the call in our logs. Quote it when you report a problem. Example |
Body: application/problem+json
| Field | Type | Description |
|---|---|---|
| type | string | Always Example |
| title required | string | The HTTP status in words. Example |
| status required | integer | The HTTP status. Example |
| code required | string | 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 |
| detail required | string | 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 |
| field | string | The key of the call that is wrong, when there is one. A name, never a value. Example |
| errors | array of object (FieldProblem) | With the code |
| errors[].field required | string | The key of the field, with dots for nested fields. A name, never a value. Example |
| errors[].code required | string | The short word that names the problem of the field. Pattern |
| errors[].detail required | string | What is wrong with the field and how to fix it, in English. Never the value sent. Example |
| existing_id | string | With the code Example |
| requestId | string | The identifier of the call in our logs. Example |
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"
}