---
title: "Update a User's Email Address"
method: PATCH
path: "/users/{user_id}/settings/emails/{email_id}/"
tags: ["Users"]
---

# Update a User's Email Address

`PATCH /users/{user_id}/settings/emails/{email_id}/`

Updates attributes of a user's email address.
#### Allowed Updates
- Set an email address as `primary` (must already be confirmed). - Mark an email as `verified` (must already be confirmed).
#### Returns
Returns the updated email address in a JSON object with a `data` key.
#### Errors
If the request is unsuccessful, an `errors` key containing information about the failure will be returned. Refer to the [list of error codes](#tag/Errors-and-Error-Codes).

## Path parameters

- `user_id` string, required
- `email_id` string, required

## Request body

- object
  - `data` object
    - `type` 'user-emails'
    - `id` string — The email ID to update. Example: `1a2b3c`
    - `attributes` object
      - `primary` boolean — Whether this email should be set as primary.
      - `verified` boolean — Whether this email should be marked as verified (requires confirmation first).

## Response `200`

Successfully updated the email address.

- object
  - `id` string, required — The unique identifier of the user entity.
  - `type` string, required — The type identifier of the user entity (`users`).
  - `attributes` object, required — The properties of the user entity.
    - `active` boolean, required — Whether or not the user is an active user.
    - `date_registered` string, date-time, required — The time at which the user registered their account, as an iso8601 formatted timestamp.
    - `family_name` string — The family name of the user, used for bibliographic citations.
    - `full_name` string, required — The full name of the user, used for display on the OSF.
    - `given_name` string — The given name of the user, used for bibliographic citations.
    - `middle_names` string — The middle names of the user, used for bibliographic citations.
    - `suffix` string — The suffix of the user, used for bibliographic citations.
    - `locale` string — The user's locale, e.g. 'en_US'.
    - `timezone` string — The user's timezone, e.g. 'Etc/UTC'.
    - `social` object — A dictionary of the user's social and academic profile links. Fields may include: - `github`, `twitter`, `linkedIn`: List of profile URLs (strings) - `scholar`, `orcid`, `researcherId`, `impactStory`, etc.: Single URL string - `profileWebsites`: List of personal website URLs (strings)
    - `employment` object[] — A list of the user's employment history records.
      - `title` string
      - `institution` string, required
      - `department` string
      - `startYear` integer, required
      - `startMonth` integer, required
      - `endYear` integer
      - `endMonth` integer
      - `ongoing` boolean, required
    - `education` object[] — A list of the user's educational history records.
      - `degree` string
      - `institution` string, required
      - `department` string
      - `startYear` integer, required
      - `startMonth` integer, required
      - `endYear` integer
      - `endMonth` integer
      - `ongoing` boolean, required
  - `relationships` object, required — URLs to other entities or entity collections that have a relationship to the user entity.
    - `institutions` string — A link to the list of institutions the user is affiliated with.
    - `nodes` string — A link to the list of nodes the user is a contributor to.
  - `links` object, required — URLs to alternative representations of the user entity.
    - `html` string, URL — A link to the user's profile page on the OSF.
    - `profile_image` string, URL — A link to the user's profile image.

## Other responses

- `400` — Bad request. This can occur if trying to set an unconfirmed email as primary or verify an unconfirmed email.
- `403` — Permission denied.
- `404` — Email address not found.

---

[API](https://skmtc.net/osf/apis/osf-apiv2-documentation.md) · [All operations](https://skmtc.net/osf/apis/osf-apiv2-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/osf/osf-apiv2-documentation/versions/ca701048eb0d/schema)