> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay-881012b3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create or Port UPI Number

> Create a new UPI Number or port an existing mobile number from another TPAP.

<div style={{display:"flex",flexWrap:"wrap",alignItems:"center",gap:"0.35rem 0.9rem",border:"1px solid rgba(128,128,128,0.28)",borderRadius:"0.5rem",padding:"0.45rem 0.75rem",margin:"0 0 1.25rem",fontSize:"0.875rem"}}>
  <span style={{fontWeight:600}}>Available in</span>
  <span>🇮🇳 India</span>
</div>

Use this endpoint to create a new UPI Number or port a mobile number to a new VPA.

<RequestExample>
  ```bash Curl theme={null}
  -X POST 'https://api.rzp.<bank>.com/v1/upi/tpap/upi_number' \
  -u [YOUR_KEY_ID]:[YOUR_SECRET] \
  -H "Content-Type: application/json" \
  -H "x-device-fingerprint: <device_fingerprint>" \
  -H "x-device-fingerprint-timestamp: 1496918882000" \
  -H "x-customer-reference: cust_ref" \
  -d '{
    "upi_number": "1234567890",
    "vpa": "gaurav.kumar@exampleupi",
    "action": "create",
    "existing_vpa": "olduser@upi",
    "consent": true
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "entity": "upi_number",
    "upi_transaction_id": "123qwert12",
    "upi_number": "1234567890",
    "type": "mobile",
    "status": "initiated",
    "vpa": "gaurav.kumar@exampleupi"
  }
  ```

  ```json Failure theme={null}
  {
    "error": {
      "code": "BAD_REQUEST_ERROR",
      "description": "Consent is mandatory",
      "source": "internal",
      "step": "",
      "reason": "user consent must be true",
      "field": "consent",
      "metadata": null
    }
  }
  ```
</ResponseExample>

## Request Parameters

<ParamField body="upi_number" type="string" required>
  The UPI number to check for availability (mobile or numeric id).
</ParamField>

<ParamField body="vpa" type="string" required>
  VPA to which the UPI number has to be linked.
</ParamField>

<ParamField body="action" type="string">
  Action to be performed on UPI Number. Possible values:

  * `create`
  * `port`
</ParamField>

<ParamField body="existing_vpa" type="string">
  VPA linked with the UPI number (Only in case of PORT).
</ParamField>

<ParamField body="consent" type="boolean" required>
  Consent of the user to create a new UPI Number or port a mobile number to a new VPA. Possible values:

  * `true`: The user has given the consent.
  * `false`: The user has not given the consent.
</ParamField>

## Response Parameters

<ResponseField name="entity" type="string">
  Collection of entity. Here it is `upi_number`.
</ResponseField>

<ResponseField name="upi_transaction_id" type="string">
  Unique transaction id created by the originator.
</ResponseField>

<ResponseField name="upi_number" type="string">
  Unique id mapped to the customer's VPA.
</ResponseField>

<ResponseField name="type" type="string">
  Type of number. For example, mobile or numeric.
</ResponseField>

<ResponseField name="status" type="string">
  Status of the UPI number. Possible values:

  * `initiated`
  * `active`
</ResponseField>

<ResponseField name="vpa" type="string">
  VPA linked to the UPI number.
</ResponseField>