Skip to content
Norbelys
Esc
↑↓navigate↵open⌘Jpreview

Update a person: its address, names, company, custom values (merged) or groups (replaced).

PATCH/v1/people/{id}
Authorization
AuthorizationBearer token · headerrequired

An API key (nb_live_…, nb_test_…), a workspace token (nbs_…) or a CLI token (nbc_…).

Path parameters
idId_Personrequired

The person id (per_…).

matches ^per_[0-9a-f]{32}$
Header parameters
If-Matchstring

The version the change applies to, quoted as the ETag that carried it ("1790000000000000"), or *. A version that is no longer current answers 412 precondition_failed and changes nothing; without the header the change applies to whatever version is current.

Idempotency-Keystring

A stable key for this logical request; reuse it when retrying.

min length 1 · max length 128 · matches ^[!-~]+$
Request body
requiredapplication/json
companystring | null
emailstring<email> | null

A new address; unique in the workspace ignoring ASCII case.

family_namestring | null
fieldsobject | null

Custom values merged into the person's; null removes one.

given_namestring | null

A new given name; null clears it.

group_idsstring[] | null

The person's groups, replacing the current ones whole; at most 100.

Responses
200

The person.

companystring | null
created_atTimestamprequired
emailstringrequired

The address as it was written; it is unique in the workspace ignoring ASCII case.

family_namestring | null
fieldsobjectrequired

The person's custom values, by field key.

given_namestring | null
group_idsId_Group[]required

The groups the person belongs to, at most 100.

idId_Personrequired
matches ^per_[0-9a-f]{32}$
last_sent_atTimestamp | null
Show properties
One of:
Timestamp
string<date-time>
null
null
replied_atTimestamp | null
Show properties
One of:
Timestamp
string<date-time>
null
null
updated_atTimestamprequired
versioninteger<int64>required

The person's version, also the response's ETag: updated_at in microseconds since the Unix epoch. An update sent with it in If-Match applies only to this version, so a replacement of group_ids never erases a membership added since it was read.

400

The body is not JSON, or If-Match is malformed (invalid_request).

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

401

No valid credential.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

403

The credential lacks people:write.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

404

No such person, or a group does not exist.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

409

Another person has the new address (conflict).

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

412

If-Match names a version that is no longer current (precondition_failed); nothing changed.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

422

The body is invalid.

codestringrequired

The code from the closed registry; programs branch on it, never on the text. New codes may be added.

detailstringrequired

What went wrong, for a person; never an internal cause.

errorsFieldError[]

With validation_failed only: every invalid field.

Show properties
Array of FieldError
codestringrequired

What is wrong (required, range, length, format, invalid, …).

detailstringrequired

A safe, human-readable explanation.

pointerstringrequired

RFC 6901 pointer into the body, or ?name for a query parameter.

instancestringrequired

The request's path.

request_idstringrequired

The request's id, also in X-Request-Id: what support needs to find the request.

retry_afterinteger<int64> | null

With 429 and 503: the seconds to wait, as in Retry-After.

min 0
statusinteger<int32>required

The HTTP status.

min 0
titlestringrequired

Fixed per code.

typestringrequired

https://docs.norbelys.com/errors/<code>, a page that explains the code.

Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X PATCH 'https://api.norbelys.com/v1/people/per_0190f8a2b4c87a10b6d2e4f6a8c0e2f4' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "company": "Analytical Engines",
  "fields": {
    "industry": null
  },
  "group_ids": [
    "grp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4"
  ]
}'
Response
{
  "company": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "email": "string",
  "family_name": "string",
  "fields": {},
  "given_name": "string",
  "group_ids": [
    "grp_0190f8a2b4c87a10b6d2e4f6a8c0e2f4"
  ],
  "id": "per_0190f8a2b4c87a10b6d2e4f6a8c0e2f4",
  "last_sent_at": "2019-08-24T14:15:22Z",
  "replied_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "version": 0
}