---
updatedAt: 2026-07-06T05:15:18.000Z
agentTools:
  projectIndex: https://partner-docs.gupshup.io/llms.txt
---

# Get reserved username suggestions

Returns reserved username suggestions for the business portfolio (higher chance of approval). A suggestion can be claimed via Set / Adopt Business Username.

## Sample Request:

```
curl --location 'https://partner.gupshup.io/partner/app/{{APP_ID}}/username/suggestions' \
--header 'Authorization: {{PARTNER_APP_TOKEN}}'
```

<br />

##

```
{
  "username_suggestions": [
    "gupshup",
    "journeybuilderflowsp",
    "k8sautomation",
    "newapril05",
    "convomatetestqa",
    "qa_cdp_gg",
    "gupshupctm",
    "shashwatgupshuptest"
  ]
}
```

<br />

<br />

| Key           | Description                      | Values                                    |
| :------------ | :------------------------------- | :---------------------------------------- |
| Authorization | Access token for the application | sk\_\*\*\*\*                              |
| APP\_ID       | App ID (path param)              | e.g. 04e6c66b-bb95-4bfc-b75e-4e7391ddc680 |

<br />

# OpenAPI definition

````json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Partner Portal - Business Username Management",
    "version": "3.0.0-SNAPSHOT"
  },
  "externalDocs": {
    "description": "Gupshup Partner Documentation",
    "url": "https://partner-docs.gupshup.io/"
  },
  "servers": [
    {
      "url": "https://partner.gupshup.io/partner",
      "description": "Production server"
    },
    {
      "url": "http://localhost:8080/partner",
      "description": "Local development server"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Business Username Management",
      "description": "Adopt, view, fetch suggestions for, and delete the business username of a WhatsApp Business phone number"
    }
  ],
  "paths": {
    "/app/{appId}/username/suggestions": {
      "get": {
        "tags": [
          "Business Username Management"
        ],
        "summary": "Get reserved username suggestions",
        "description": "Returns reserved username suggestions for the business portfolio (higher chance of approval). A suggestion can be claimed via Set / Adopt Business Username.",
        "operationId": "getBusinessUsernameSuggestions",
        "parameters": [
          {
            "name": "appId",
            "in": "path",
            "description": "Application ID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "04e6c66b-bb95-4bfc-b75e-4e7391ddc680"
          }
        ],
        "responses": {
          "200": {
            "description": "Success - Meta passthrough with username_suggestions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsernameSuggestionsResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Success",
                    "value": {
                      "username_suggestions": [
                        "gupshup",
                        "journeybuilderflowsp",
                        "k8sautomation",
                        "newapril05",
                        "convomatetestqa",
                        "qa_cdp_gg",
                        "gupshupctm",
                        "shashwatgupshuptest"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation error or Meta error body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessUsernameErrorResponse"
                },
                "examples": {
                  "invalidAppDetails": {
                    "summary": "Unknown / invalid appId",
                    "value": {
                      "message": "Invalid App Details",
                      "status": "error"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed - invalid or missing Partner App token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessUsernameErrorResponse"
                },
                "examples": {
                  "authenticationFailed": {
                    "summary": "Authentication failed",
                    "value": {
                      "status": "error",
                      "message": "Unauthorised access to the resource. Please review request parameters and headers and retry"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error - unexpected portal failure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessUsernameErrorResponse"
                },
                "examples": {
                  "serverError": {
                    "summary": "Internal server error",
                    "value": {
                      "status": "error",
                      "message": "Unable to get business username suggestions for app id: {appId}"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "UsernameSuggestionsResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "username_suggestions": {
            "type": "array",
            "description": "Reserved username suggestions",
            "items": {
              "type": "string"
            },
            "example": [
              "gupshup",
              "journeybuilderflowsp",
              "k8sautomation"
            ]
          }
        },
        "additionalProperties": true,
        "description": "Meta passthrough success response with username suggestions"
      },
      "BusinessUsernameErrorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ],
            "example": "error"
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message",
            "example": "Invalid App Details"
          }
        },
        "description": "Error response from Partner Portal or upstream"
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Partner App access token with `PARTNER_APP` role.\n\n**How to obtain:**\n1. Authenticate as a partner user (login flow for your environment)\n2. Call `GET /partner/app/{appId}/token` with the user JWT\n3. Use the returned app token as `Authorization: Bearer <token>`\n\n**Example:**\n```\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\n```\n"
      }
    }
  }
}
````