Collect user profile

Beyond authentication identifiers and credentials required for user sign-in, your application may need to collect additional user profile information stored in Logto for easy retrieval via JWT claims or APIs to provide personalized product experiences. You can collect user data through the following methods:

• During new user registration: Use the Collect user profile feature to add an out-of-the-box "Tell us about yourself" step that collects additional user profile information during sign-up. New users must complete all required fields before registration is considered finished. This doc focuses on this approach.

• After user registration: Use the Account API to implement self-service experiences during onboarding flows, account centers, or throughout the product usage journey to update user profile information.

Key benefits

The Collect user profile feature enables you to gather additional user information during the end-user registration experience. We recommend collecting only essential information required for your product to avoid lengthy registration flows that may impact user conversion rates.

This feature allows you to:

• Capture comprehensive user data: Collect any user data for business or compliance purposes, including OIDC standard user properties and custom data.

• Flexible field customization: Choose from various field types including text, number, date, checkbox, dropdown (select), URL, and regex validation to match your specific data requirements.

• Optimized user experience: Customize the display with labels, descriptions, placeholders, and validation rules. Configure fields as required or optional based on your business needs.

• Built-in field configurations: Use pre-configured basic data fields for common user properties with plug-and-play setup. Leverage composite fields (address, fullname) to gather structured data efficiently in a single step.

Quick start

1. Go to Logto console > Sign-in Experience > Collect user profile.
2. Click "Add profile fields" and choose a built-in field or define a custom data (alphanumeric key) to create.
3. Open field details to set field type, label, description, required flag, and type-specific settings (length, range, format, options, etc.). Click "Save changes".
4. Back to the Sign-in experience > Collect user profile, drag and drop the fields to reorder these fields, and the changes will automatically apply.
5. Test the user experience with Logto live preview or your test app. Whether users create a new account via identifier (email/phone number/username), social sign-in, or Enterprise SSO, they will all see the "Tell us about yourself" page during registration.

User data types

User data can be viewed in each user profile. For a comprehensive overview of all user data categories, refer to the User data structure documentation. The Collect user profile feature allows you to gather both basic user data and custom user data during registration.

Basic user data fields

Basic user data fields provided by Logto are stored directly in user or user.profile property. These fields come with default configuration values and i18n translations, ready to use immediately after creation. You can also customize field types and parameters according to your specific requirements.

Field Name	User data key	Description
Name	user.name	The user's full name in displayable form including all name components (e.g., "Jane Doe").
Fullname	user.profile.givenName user.profile.middleName user.profile.familyName	The user’s complete legal name. Flexibly combines familyName, givenName, and middleName based on configuration.
Nickname	user.profile.nickname	Casual or familiar name for the user, which may differ from their legal name.
Birthdate	user.profile.birthdate	The user's date of birth in a specified format (e.g., "MM-dd-yyyy").
Gender	user.profile.gender	The user's self-identified gender (e.g., "Female", "Male", "Prefer not to say").
Profile	user.profile.profile	URL of the user's human-readable profile page (e.g., social media profile).
Website	user.profile.website	URL of the user's personal website or blog.
Address	user.profile.address.formatted user.profile.address.streetAddress user.profile.address.region user.profile.address.zoneinfo user.profile.address.postalCode user.profile.address.country	The user's full address (e.g., "123 Main St, Anytown, USA 12345"). Choose between single-line (address.formatted) or multi-line with configurable components (street, city, state, zip code, country).

Custom user data fields

Custom user data fields are user-defined fields that capture additional information not covered by the basic fields, such as preferences, interests, company size, or other business-specific attributes.

When creating custom fields, use alphanumeric characters only for the user data key (e.g., customData.companySize). You can then configure the field type and customize additional properties to meet your specific requirements.

For more information on retrieving and updating custom user data after user creation, see user data structure.

Field types

We can simply categorize fields by simplicity:

• Primitive: Text, Number, Date, Checkbox (Boolean), Dropdown (Single select), URL, Regular expression.
• Composite: Fullname, Address.

Common properties

Property	Applies to	Notes
Label	All	Display name shown to users. Floats to the top when field has value or is focused. This is a required field.
Placeholder	All (except Checkbox)	Inline hint visible when the label is floating (example text / formatting guidance).
Description	All (except Checkbox)	Supporting text beneath the field for longer instructions or extra context.
Required	All (except Checkbox)	If enabled, submission is blocked when empty. If disabled, an (Optional) tag is appended to the label.

Type-specific configurations

Type	Configurable aspects	Notes
Text	min/max length	Limit the minimum and maximum length of the user input text.
Number	min/max value	Limit the minimum and maximum numeric range of the input value.
Date	Date format (preset/custom)	Choose preset formats (MM/dd/yyyy, dd/MM/yyyy, yyyy-MM-dd). Changing placeholder overrides default interactions. Or use fully customizable date-fns patterns.
Checkbox	Default value	Checked (True) / Unchecked (False).
Dropdown (Select)	Option list (≥1)	Use value:label per line. If label omitted, the value is displayed.
URL	N/A	N/A
Regex	Regular expression	Validation pattern (omit leading/trailing slashes). E.g. ^\d3-\d2-\d4$ for SSN.
Address	Components	Single or multi-line; sub-components: street, city, state, zip code, country.
Fullname	Components	Sub-components: first, middle, last name.

Validation

Field validation is performed on user submission in the final step of registration. The following checks are enforced:

• Required presence (except Checkbox).
• Length boundaries (Text).
• Numeric range (Number).
• Pattern match (Regex, Date with format, URL, Select option membership).
• URL structure (basic syntactic validation, not reachability).

Also applies to the sub-components of the two composite fields: address and fullname. The individual components must also meet the same validation criteria.

Localization

Logto provides system level translations for the basic user data fields, such as firstName, lastName, gender, and birthdate. The label of these fields are configurable in Logto Console. You can override these labels by providing your own translations in Logto > Sign-in Experience > Content

Custom fields rely entirely on the labels, placeholders, and descriptions you provide. For custom field localization, you can handle translations by using Bring your UI or contact us with your feedback.

Management API (key endpoints)

Method	Endpoint	Purpose
GET	/api/custom-profile-fields	List all fields.
GET	/api/custom-profile-fields/:name	Fetch single field definition by name.
POST	/api/custom-profile-fields	Create a field.
POST	/api/custom-profile-fields/batch	Bulk create (≤20 items per request).
PUT	/api/custom-profile-fields/:name	Update field by name and full dataset.
DELETE	/api/custom-profile-fields/:name	Delete a field.
POST	/api/custom-profile-fields/properties/sie-order	Update field ordering in Sign-in Experience.

Best practices

• Collect only essential data at sign-up; defer nice-to-have info to later profile completion.
• Use composite fields for structured data (address, fullname) for consistency and localization.
• Provide clear examples/placeholders for format-sensitive fields (regex, date, numeric ranges).

FAQs

Do the profile fields collect existing user data?

No, they only collect information from the final step of new user registration.

What if I delete a field? Does it remove the user data?

No, it will not remove the existing user data. Only the field will be removed from the sign-up form in the end-user experience.

Can I collect country with a controlled list instead of a regular text field?

Yes, you can switch the "Country" component to a "Dropdown (Single select)" field with standardized options.