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

# Set / adopt business username

Adopts or changes the business username for the app's WhatsApp phone number.

## Sample Request:

```
curl --location 'https://partner.gupshup.io/partner/app/{{APP_ID}}/username' \
--header 'Authorization: {{PARTNER_APP_TOKEN}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=<USERNAME>' \
--data-urlencode 'transfer_action=none'
```

<br />

## Sample Response:

```
{
  "status": "reserved"
}
```

<br />

| Key              | Description                      | Value                                     |
| :--------------- | :------------------------------- | :---------------------------------------- |
| Authorization    | Access token for the application | sk\_\*\*\*\*\*                            |
| Content-Type     | Request media type               | application/x-www-form-urlencoded         |
| APP\_ID          | App ID (path param)              | e.g. 04e6c66b-bb95-4bfc-b75e-4e7391ddc680 |
| username         | Desired business username        | e.g. mybusiness                           |
| transfer\_action | Username transfer action         | none, force\_transfer                     |

<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": {
      "post": {
        "tags": [
          "Business Username Management"
        ],
        "summary": "Set / adopt business username",
        "description": "Adopts or changes the business username for the app's WhatsApp phone number.",
        "operationId": "setBusinessUsername",
        "parameters": [
          {
            "name": "appId",
            "in": "path",
            "description": "Application ID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "04e6c66b-bb95-4bfc-b75e-4e7391ddc680"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/SetBusinessUsernameRequest"
              },
              "examples": {
                "setUsername": {
                  "summary": "Set business username",
                  "value": {
                    "username": "mybusiness",
                    "transfer_action": "none"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success - Meta passthrough (approved: username approved; reserved: reserved until feature GA)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessUsernameStatusResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Success",
                    "value": {
                      "status": "reserved"
                    }
                  },
                  "OK": {
                    "summary": "OK",
                    "value": {
                      "status": "approved"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - validation error or Meta error body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessUsernameErrorResponse"
                },
                "examples": {
                  "usernameEmpty": {
                    "summary": "Username form param missing",
                    "value": {
                      "message": "Username cannot be empty",
                      "status": "error"
                    }
                  },
                  "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": "Authentication Failed"
                    }
                  }
                }
              }
            }
          },
          "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 set business username for app id: {appId}"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "SetBusinessUsernameRequest": {
        "type": "object",
        "required": [
          "username"
        ],
        "properties": {
          "username": {
            "type": "string",
            "description": "Desired business username. Letters (a-z), digits (0-9), period (.), underscore (_); see Meta docs for full rules.",
            "example": "mybusiness"
          },
          "transfer_action": {
            "type": "string",
            "description": "Username transfer action. Defaults to none. Use force_transfer on Meta error 147005.",
            "enum": [
              "none",
              "force_transfer"
            ],
            "example": "none"
          }
        },
        "description": "Form-urlencoded request body for setting / adopting the business username"
      },
      "BusinessUsernameStatusResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "Upstream status (e.g. success, approved, reserved)",
            "example": "success"
          },
          "username": {
            "type": "string",
            "description": "Current business username (returned by Get current business username)",
            "example": "mybusiness"
          }
        },
        "additionalProperties": true,
        "description": "Meta passthrough success response"
      },
      "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"
      }
    }
  }
}
````