Update User - Serval Documentation

PUT

users

{id}

Update User

curl --request PUT \
  --url https://public.api.serval.com/v2/users/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "firstName": "<string>",
  "lastName": "<string>",
  "avatarUrl": "<string>",
  "locale": "<string>",
  "phoneNumber": "<string>",
  "releaseFields": [],
  "timezone": "<string>",
  "pinFields": [],
  "department": "<string>",
  "jobTitle": "<string>"
}
'

import requests

url = "https://public.api.serval.com/v2/users/{id}"

payload = {
    "email": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "avatarUrl": "<string>",
    "locale": "<string>",
    "phoneNumber": "<string>",
    "releaseFields": [],
    "timezone": "<string>",
    "pinFields": [],
    "department": "<string>",
    "jobTitle": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: '<string>',
    firstName: '<string>',
    lastName: '<string>',
    avatarUrl: '<string>',
    locale: '<string>',
    phoneNumber: '<string>',
    releaseFields: [],
    timezone: '<string>',
    pinFields: [],
    department: '<string>',
    jobTitle: '<string>'
  })
};

fetch('https://public.api.serval.com/v2/users/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://public.api.serval.com/v2/users/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => '<string>',
    'firstName' => '<string>',
    'lastName' => '<string>',
    'avatarUrl' => '<string>',
    'locale' => '<string>',
    'phoneNumber' => '<string>',
    'releaseFields' => [
        
    ],
    'timezone' => '<string>',
    'pinFields' => [
        
    ],
    'department' => '<string>',
    'jobTitle' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://public.api.serval.com/v2/users/{id}"

	payload := strings.NewReader("{\n  \"email\": \"<string>\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"avatarUrl\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"releaseFields\": [],\n  \"timezone\": \"<string>\",\n  \"pinFields\": [],\n  \"department\": \"<string>\",\n  \"jobTitle\": \"<string>\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://public.api.serval.com/v2/users/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"<string>\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"avatarUrl\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"releaseFields\": [],\n  \"timezone\": \"<string>\",\n  \"pinFields\": [],\n  \"department\": \"<string>\",\n  \"jobTitle\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.api.serval.com/v2/users/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"<string>\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"avatarUrl\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"releaseFields\": [],\n  \"timezone\": \"<string>\",\n  \"pinFields\": [],\n  \"department\": \"<string>\",\n  \"jobTitle\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "<string>",
    "email": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "name": "<string>",
    "role": "USER_ROLE_UNSPECIFIED",
    "avatarUrl": "<string>",
    "createdAt": "2025-01-15T01:30:15.000Z",
    "deactivatedAt": "2025-01-15T01:30:15.000Z",
    "timezone": "<string>",
    "authMethod": "USER_AUTH_METHOD_UNSPECIFIED",
    "locale": "<string>",
    "department": "<string>",
    "jobTitle": "<string>"
  },
  "skippedPinnedFields": [
    "USER_PROFILE_FIELD_UNSPECIFIED"
  ],
  "skippedDirectoryLockedFields": [
    "USER_PROFILE_FIELD_UNSPECIFIED"
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

string

required

Body

application/json

Governed profile fields (first/last name, avatar, locale, timezone) carry per-field provenance: a user-token edit pins the field so automation cannot overwrite it, and a directory-synced value locks it against everyone but the directory. Writes from API-key or worker tokens to a pinned or locked field are skipped — the rest of the update still applies, and the skipped fields are reported in the response — unless the field is listed in pin_fields, which makes the write a deliberate edit that replaces the pin (directory locks still win). A pinned field whose requested value already matches the pinned one succeeds as a clean no-op (not reported as skipped); a directory-locked field is always reported as skipped, even when the requested value matches. User-token writes replace pins but are rejected on directory-locked fields (change those in the IdP).

string | null

The address the user logs in with, unique per organization and compared case-insensitively. Two rejections to expect: an email your directory supplies is only changeable in the identity provider, and an address another user in the organization already holds is refused — including a deactivated user's, because deactivating does not release it. The error names the user holding the address so you can move them off it first. Change email in a request by itself. Because login identity is global, an organization-scoped caller cannot rename a user who belongs to multiple organizations.

firstName

string | null

lastName

string | null

role

enum<string> | null

Available options:

USER_ROLE_UNSPECIFIED,

USER_ROLE_ORG_MEMBER,

USER_ROLE_ORG_ADMIN,

USER_ROLE_ORG_GUEST

avatarUrl

string | null

authMethod

enum<string> | null

Specifies the authentication method for a user. If unset, the org default applies. Set to MAGIC_LINK to allow the user to bypass SSO (e.g. guest or break-glass accounts).

Available options:

USER_AUTH_METHOD_UNSPECIFIED,

USER_AUTH_METHOD_MAGIC_LINK

locale

string | null

BCP 47 language tag

phoneNumber

string | null

releaseFields

enum<string>[]

Profile fields to hand back to automation (user ingestion). A pinned field keeps its current value but loses that protection, so the next ingestion sync may update it again. A field cannot be both set and released in the same request.

The governed user profile fields, which carry per-field provenance and edit protection.

Available options:

USER_PROFILE_FIELD_UNSPECIFIED,

USER_PROFILE_FIELD_FIRST_NAME,

USER_PROFILE_FIELD_LAST_NAME,

USER_PROFILE_FIELD_AVATAR_URL,

USER_PROFILE_FIELD_TIMEZONE,

USER_PROFILE_FIELD_LOCALE,

USER_PROFILE_FIELD_MANAGER,

USER_PROFILE_FIELD_DEPARTMENT,

USER_PROFILE_FIELD_JOB_TITLE

timezone

string | null

IANA timezone, e.g., "America/New_York"

pinFields

enum<string>[]

Profile fields to pin against automation (user ingestion) overwrites. Edits made with a user token pin by default; API-key edits stay unpinned unless listed here. A pinned field must be set in the same request, and stays pinned until released (release_fields) or replaced by a later deliberate edit. avatar_url cannot be pinned; manager is pinned through the relationship endpoints' pin flag.

The governed user profile fields, which carry per-field provenance and edit protection.

Available options:

USER_PROFILE_FIELD_UNSPECIFIED,

USER_PROFILE_FIELD_FIRST_NAME,

USER_PROFILE_FIELD_LAST_NAME,

USER_PROFILE_FIELD_AVATAR_URL,

USER_PROFILE_FIELD_TIMEZONE,

USER_PROFILE_FIELD_LOCALE,

USER_PROFILE_FIELD_MANAGER,

USER_PROFILE_FIELD_DEPARTMENT,

USER_PROFILE_FIELD_JOB_TITLE

department

string | null

Department; empty string clears. Any saved value joins the org's department options automatically, adopting the casing of an existing case-insensitive match.

jobTitle

string | null

Free-text job title; empty string clears.

Response

200 - application/json

Success

data

data · object

Show child attributes

skippedPinnedFields

enum<string>[]

Requested profile fields this update did NOT apply because a manual (user-token) edit owns them. Only ever populated for API-key/worker callers — automation may not overwrite a deliberate human edit, so those fields keep their current value while the rest of the update applies. Empty when everything applied, including when the requested value already matched the pinned one.

The governed user profile fields, which carry per-field provenance and edit protection.

Available options:

USER_PROFILE_FIELD_UNSPECIFIED,

USER_PROFILE_FIELD_FIRST_NAME,

USER_PROFILE_FIELD_LAST_NAME,

USER_PROFILE_FIELD_AVATAR_URL,

USER_PROFILE_FIELD_TIMEZONE,

USER_PROFILE_FIELD_LOCALE,

USER_PROFILE_FIELD_MANAGER,

USER_PROFILE_FIELD_DEPARTMENT,

USER_PROFILE_FIELD_JOB_TITLE

skippedDirectoryLockedFields

enum<string>[]

Requested profile fields this update did NOT apply because the org's directory (IdP sync) supplies them. Populated for API-key/worker callers; user-token writes to directory-locked fields fail the request instead. Unlike pins, a directory-locked field is reported here even when the requested value matches the locked one — the lock gates before any value comparison.

The governed user profile fields, which carry per-field provenance and edit protection.

Available options:

USER_PROFILE_FIELD_UNSPECIFIED,

USER_PROFILE_FIELD_FIRST_NAME,

USER_PROFILE_FIELD_LAST_NAME,

USER_PROFILE_FIELD_AVATAR_URL,

USER_PROFILE_FIELD_TIMEZONE,

USER_PROFILE_FIELD_LOCALE,

USER_PROFILE_FIELD_MANAGER,

USER_PROFILE_FIELD_DEPARTMENT,

USER_PROFILE_FIELD_JOB_TITLE

Update User

curl --request PUT \
  --url https://public.api.serval.com/v2/users/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "firstName": "<string>",
  "lastName": "<string>",
  "avatarUrl": "<string>",
  "locale": "<string>",
  "phoneNumber": "<string>",
  "releaseFields": [],
  "timezone": "<string>",
  "pinFields": [],
  "department": "<string>",
  "jobTitle": "<string>"
}
'

import requests

url = "https://public.api.serval.com/v2/users/{id}"

payload = {
    "email": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "avatarUrl": "<string>",
    "locale": "<string>",
    "phoneNumber": "<string>",
    "releaseFields": [],
    "timezone": "<string>",
    "pinFields": [],
    "department": "<string>",
    "jobTitle": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: '<string>',
    firstName: '<string>',
    lastName: '<string>',
    avatarUrl: '<string>',
    locale: '<string>',
    phoneNumber: '<string>',
    releaseFields: [],
    timezone: '<string>',
    pinFields: [],
    department: '<string>',
    jobTitle: '<string>'
  })
};

fetch('https://public.api.serval.com/v2/users/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://public.api.serval.com/v2/users/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => '<string>',
    'firstName' => '<string>',
    'lastName' => '<string>',
    'avatarUrl' => '<string>',
    'locale' => '<string>',
    'phoneNumber' => '<string>',
    'releaseFields' => [
        
    ],
    'timezone' => '<string>',
    'pinFields' => [
        
    ],
    'department' => '<string>',
    'jobTitle' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://public.api.serval.com/v2/users/{id}"

	payload := strings.NewReader("{\n  \"email\": \"<string>\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"avatarUrl\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"releaseFields\": [],\n  \"timezone\": \"<string>\",\n  \"pinFields\": [],\n  \"department\": \"<string>\",\n  \"jobTitle\": \"<string>\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://public.api.serval.com/v2/users/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"<string>\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"avatarUrl\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"releaseFields\": [],\n  \"timezone\": \"<string>\",\n  \"pinFields\": [],\n  \"department\": \"<string>\",\n  \"jobTitle\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://public.api.serval.com/v2/users/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"<string>\",\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"avatarUrl\": \"<string>\",\n  \"locale\": \"<string>\",\n  \"phoneNumber\": \"<string>\",\n  \"releaseFields\": [],\n  \"timezone\": \"<string>\",\n  \"pinFields\": [],\n  \"department\": \"<string>\",\n  \"jobTitle\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "<string>",
    "email": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "name": "<string>",
    "role": "USER_ROLE_UNSPECIFIED",
    "avatarUrl": "<string>",
    "createdAt": "2025-01-15T01:30:15.000Z",
    "deactivatedAt": "2025-01-15T01:30:15.000Z",
    "timezone": "<string>",
    "authMethod": "USER_AUTH_METHOD_UNSPECIFIED",
    "locale": "<string>",
    "department": "<string>",
    "jobTitle": "<string>"
  },
  "skippedPinnedFields": [
    "USER_PROFILE_FIELD_UNSPECIFIED"
  ],
  "skippedDirectoryLockedFields": [
    "USER_PROFILE_FIELD_UNSPECIFIED"
  ]
}