---
title: Forgotten username REST requests
description: The following REST requests and responses demonstrate the flow through a forgotten username process:
component: pingidm
version: 7.2
page_id: pingidm:self-service-reference:username-rest-flow
canonical_url: https://docs.pingidentity.com/pingidm/7.5/self-service-reference/username-rest-flow.html
llms_txt: https://docs.pingidentity.com/pingidm/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
superseded_by: https://docs.pingidentity.com/pingidm/7.5/self-service-reference/username-rest-flow.html
---

# Forgotten username REST requests

The following REST requests and responses demonstrate the flow through a forgotten username process:

1. Client initiates the username retrieval process. The server returns the initial set of requirements:

   ```
   curl \
    --header "X-OpenIDM-Username: anonymous" \
    --header "X-OpenIDM-Password: anonymous" \
    --header "X-OpenIDM-NoSession: true" \
    --request GET \
    "https://localhost:8443/openidm/selfservice/username"
   {
      "_id":"1",
      "_rev":"959264722",
      "type":"userQuery",
      "tag":"initial",
      "requirements":{
         "$schema":"http://json-schema.org/draft-04/schema#",
         "description":"Find your account",
         "type":"object",
         "required":[
            "queryFilter"
         ],
         "properties":{
            "queryFilter":{
               "description":"filter string to find account",
               "type":"string"
            }
         }
      }
   }
   ```

2. Client submits the requirements, along with the token. Server returns the username and the `end` tag to indicate the end of the process:

   ```
   curl \
    --header "X-OpenIDM-Username: anonymous" \
    --header "X-OpenIDM-Password: anonymous" \
    --request POST \
    --data '{
     "token": "eyJ0eXAiOiJKV1QiLCJjdHkiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ZXlKMGVY…​W5ywOcr8",
     {
        "input":{
           "queryFilter":"mail eq \"babs.k.jensen@gmail.com\""
     }
   }' \
    "https://localhost:8443/openidm/selfservice/username?_action=submitRequirements"
   {
      "type":"retrieveUsername",
      "tag":"end",
      "status":{
         "success":true
      },
      "additions":{
         "userName":"bjensen"
      }
   }
   ```