---
title: 'Custom user attributes'
description: 'Define custom profile fields, let users edit them, fetch them from the Users API, and save updates.'
keywords: ["user attributes API", "custom user fields", "user metadata Web3", "profile attributes"]
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.snagsolutions.io/llms.txt). Append `.md` to any page URL for its markdown version.

You can add custom fields to user profiles and use them across your website and APIs.

<Tip>
  Custom attributes are ideal for capturing structured data like "Favorite Team"
  or "External Profile Link" that isn't part of the default profile.
</Tip>

## Where custom attributes come from

- You can define attributes in Admin → Customization → User Profiles.
- Or you can create them via API.

<Steps>
<Step title="Create a custom user attribute (UI or API)">
If you're using the Admin UI, add a new field in the User Profiles section. To use the API, create attributes with a label that users will see.

- API: See [Create a new website user attribute](https://docs.snagsolutions.io/api-reference/identity/create-a-new-website-user-attribute).

<Check>
  You should see the new attribute in Admin → Customization → User Profiles.
</Check>

<Warning>
You must include a valid `X-API-KEY`. Missing or invalid keys result in 403 Forbidden.
</Warning>
</Step>

<Step title="Let users edit attributes in the profile modal">
In Snag's template, custom attributes appear as editable fields in the Edit Profile modal automatically. No extra code is required after you create the attributes.

<Info>
Field order and labels come from how you configured attributes in Admin or via the API.
</Info>
</Step>

<Step title="Fetch users along with their attribute values">
Use the Users API to retrieve users and their saved values for any defined attributes.

- API: See [Get users](https://docs.snagsolutions.io/api-reference/identity/get-users).

<Check>
Confirm the response includes each user and their stored values for the attributes you defined.
</Check>
</Step>

<Step title="Save or update a user's attribute value via API">
When a user edits their profile (or when you set values server-side), upsert attribute values using the attribute values endpoint.

- API: See [Create a new website user attribute value](https://docs.snagsolutions.io/api-reference/identity/create-a-new-website-user-attribute-value).

<Check>
Re-fetch the user and verify the updated value appears.
</Check>
</Step>
</Steps>

<AccordionGroup>
<Accordion title="403 Forbidden">
- **Cause**: Missing or invalid `X-API-KEY`, or insufficient permissions.
- **Fix**: Provide a valid API key with permission to write attributes/values for the given `websiteId` and `organizationId`.
</Accordion>

<Accordion title="400 Validation error">
  - **Cause**: Missing required fields (`websiteId`, `organizationId`, `data`),
  or invalid IDs. - **Fix**: Ensure all IDs are valid UUIDs and the `data` array
  has the correct shape.
</Accordion>

<Accordion title="User not updated after save">
- **Cause**: Value upsert succeeded, but UI cache not refreshed.
- **Fix**: Re-fetch the user or invalidate client cache after saving.
</Accordion>
</AccordionGroup>

## Related APIs

- [Create a new website user attribute — see API reference](https://docs.snagsolutions.io/api-reference/identity/create-a-new-website-user-attribute).
- [Get users — see API reference](https://docs.snagsolutions.io/api-reference/identity/get-users).
- [Create a new website user attribute value — see API reference](https://docs.snagsolutions.io/api-reference/identity/create-a-new-website-user-attribute-value).

<Tip>
  Use consistent labels and avoid storing secrets or sensitive PII in custom
  attributes.
</Tip>