User profile fields - Serval Documentation

Nine user profile fields are governed: Serval tracks where each value came from and decides who is allowed to change it next. If a workflow sets a user’s locale and the nightly directory sync keeps reverting it, this page explains why and how to make the value stick. The governed fields are first_name, last_name, avatar_url, timezone, locale, department, job_title, manager, and primary_phone. Email and role aren’t governed by field pinning. email is ungoverned but not unprotected, because it is the address people log in with. Two rules apply to changing it on PUT /v2/users/{id}:

If the user came from your directory, change their email in your identity provider. Serval rejects the write rather than let the next sync silently revert it.
Two users in one organization cannot share an address, and deactivating a user does not release theirs. If the address you want is already taken, the error names the user holding it. Move that user to another address first, then retry.
Change email by itself. A rename crosses the user database and login system, so Serval rejects requests that combine it with other profile changes.
A user who belongs to multiple organizations can’t be renamed through this endpoint. Login identity is global, while the API caller is scoped to one organization.

You pin department and job_title the same way as locale: list USER_PROFILE_FIELD_DEPARTMENT or USER_PROFILE_FIELD_JOB_TITLE in pinFields. Any department value you save joins the org’s set of department options automatically.

Who wins

Three classes of writer compete for a governed field. The highest-ranked writer that has touched the field owns it.

Rank	Writer	How a value gets here
1	Directory sync	Your IdP, through SCIM or directory sync. Locks the field against everyone else, including you.
2	Pinned deliberate edit	A person editing in the Serval UI, or an API call that pinned the field. Blocks automation.
3	Automation	User ingestion, connected apps, and unpinned API calls.

A pin protects a field from automation. It doesn’t protect it from directory sync: if your IdP supplies a value, change it in the IdP.

Pinning depends on your token

Whether a write pins by default depends on how you authenticated:

User token: pins by default. A person editing their own profile owns that value.
API key or worker token: doesn’t pin. Your write stays automation-class unless you ask for a pin explicitly.

That default is why a workflow’s edits get overwritten: an API key writing locale looks identical to ingestion writing locale, so the next sync is free to replace it.

Pin a field

List the field in pinFields on PUT /v2/users/{id}:

{
  "locale": "fr-FR",
  "pinFields": ["USER_PROFILE_FIELD_LOCALE"]
}

The field is now pinned. Ingestion and connected apps can no longer change it, and it stays pinned until you release it or a later deliberate edit replaces it.

A pinned field must be set in the same request. You can’t pin a value that’s already stored. Send the value and the pin together, so the request’s outcome doesn’t depend on state you can’t see.

Two fields are special:

avatar_url can’t be pinned. Avatars live under a predictable key that automation can overwrite in place, so a pin wouldn’t protect the image. Listing it returns 400.
manager pins through the relationship endpoints, not here. See Manager.

An explicit pin replaces whatever pin was there before, including one a person set in the UI. Reach for it only when your workflow should own the field. You can also pin at creation time. POST /v2/users accepts pinFields for the two fields you can seed there, first_name and last_name:

{
  "email": "ada@example.com",
  "firstName": "Ada",
  "pinFields": ["USER_PROFILE_FIELD_FIRST_NAME"]
}

Without pins, the values you seed at creation stay open for ingestion to enrich.

When your write doesn’t land

An API-key write to a field someone else owns doesn’t fail. Serval applies the rest of the update and tells you what it skipped:

{
  "data": { "...": "the updated user" },
  "skippedPinnedFields": ["USER_PROFILE_FIELD_FIRST_NAME"],
  "skippedDirectoryLockedFields": ["USER_PROFILE_FIELD_LAST_NAME"]
}

The response is still 200. Check these two arrays if your workflow depends on the write landing.

skippedPinnedFields: a person, or another deliberate edit, owns this field. Send pinFields to take ownership.
skippedDirectoryLockedFields: your IdP supplies this field. Change it there. No API call can take it.

Two details worth knowing:

If you write the value a pin already holds, the request succeeds cleanly and the field isn’t reported as skipped. Re-asserting the current state is a no-op, not a conflict.
A directory-locked field is always reported, even when your value matches. Serval checks the lock before comparing values.

User tokens behave differently. A user-token write replaces pins without complaint, but a write to a directory-locked field fails the entire request with 400 rather than skipping the field.

Release a field

Releasing hands a field back to automation. The current value stays, but loses its protection, so the next sync may replace it.

{
  "releaseFields": ["USER_PROFILE_FIELD_LOCALE"]
}

Release works with both user tokens and API keys: if you can pin a field, you can hand it back. You can’t set and release the same field in one request.

Primary phone

A phone number can belong to only one user in an organization. If connected-app ingestion supplies a primary phone that another user already owns, Serval skips that phone and publishes the remaining profile fields. The existing phone assignments stay unchanged. Direct phone edits still reject duplicate assignments. The skipped value remains in the source data. Resolving the conflicting assignment alone doesn’t retry an unchanged profile; the phone is reconsidered when the source profile changes or the user is explicitly republished.

Manager

manager is written through the relationship endpoints rather than PUT /v2/users/{id}, so its pin lives there too. Assign a manager with POST /v2/user-relationships and pin the assignment:

{
  "userId": "<user-id>",
  "relatedUserId": "<manager-id>",
  "relationshipType": "USER_RELATIONSHIP_TYPE_MANAGER",
  "pin": true
}

Clear a manager with DELETE /v2/user-relationships/{user_id}, passing pin as a query parameter. Pinning a delete pins the cleared state, so ingestion can’t re-assign the manager it thinks the user should have. The same token defaults apply: user tokens pin, API keys don’t. Pass pin: false from a user token to assign a manager without taking ownership of the field. To hand the manager field back to ingestion, release it through PUT /v2/users/{id}:

{
  "releaseFields": ["USER_PROFILE_FIELD_MANAGER"]
}

What’s next

Update User

Full request and response schema, including pinFields and releaseFields.

Create User Relationship

Assign a manager and pin the reporting line.

Connect your IdP

Directory sync outranks every pin. Fields your IdP supplies are changed there.

Databases field precedence

The equivalent model for Databases item types.

​Who wins

​Pinning depends on your token

​Pin a field

​When your write doesn’t land

​Release a field

​Primary phone

​Manager

​What’s next

Update User

Create User Relationship

Connect your IdP

Databases field precedence

Who wins

Pinning depends on your token

Pin a field

When your write doesn’t land

Release a field

Primary phone

Manager

What’s next