# Release a phone number (/docs/api-reference/phone-numbers/releasePhoneNumber)

> Give up a phone number and stop its rental, so it is not charged at the next renewal. Only a number currently allocated to the account can be released.

**POST** `/phone_number/release`

Give up a phone number and stop its rental, so it is not charged at the
next renewal. Only a number currently allocated to the account can be
released.

```yaml
operationId: releasePhoneNumber
requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        required:
          - phone_number
        properties:
          phone_number:
            type: string
            description: The number to release.
            example: '+15551234567'
          user_id:
            type: integer
            description: 'Reseller accounts only: the client to act on. Omit it to act on your own account.'
      example:
        phone_number: '+15551234567'
responses:
  '200':
    description: The number was released.
    content:
      application/json:
        schema:
          type: object
          properties:
            success:
              type: boolean
            phone_number:
              type: string
            status:
              type: string
              enum:
                - released
        example:
          success: true
          phone_number: '+15551234567'
          status: released
  '400':
    description: The request body is missing a required field.
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              description: Machine-readable error code.
            error_description:
              type: string
              description: Human-readable explanation.
        example:
          error: invalid_request
          error_description: 'Missing required fields: phone_number.'
  '401':
    description: Missing or invalid API key.
  '403':
    description: |
      A `user_id` was sent by a key that is not a reseller admin, or
      the named client's account is currently unavailable.
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              description: Machine-readable error code.
            error_description:
              type: string
              description: Human-readable explanation.
        example:
          error: forbidden
          error_description: Access denied. Only reseller accounts can use this endpoint.
  '404':
    description: |
      The `user_id` did not name one of your clients (`not_found`),
      or the account holds no such number (`number_not_found`).
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              description: Machine-readable error code.
            error_description:
              type: string
              description: Human-readable explanation.
        example:
          error: number_not_found
          error_description: No such number on this user.
  '422':
    description: The number could not be released.
    content:
      application/json:
        schema:
          type: object
          properties:
            error:
              type: string
              description: Machine-readable error code.
            error_description:
              type: string
              description: Human-readable explanation.
        example:
          error: release_failed
          error_description: The number could not be released. Please try again or contact support.
  '500':
    description: Unexpected server error.
    content:
      application/json:
        schema:
          allOf:
            - type: object
              properties:
                error:
                  type: string
                  description: Machine-readable error code.
                error_description:
                  type: string
                  description: Human-readable explanation.
            - type: object
              properties:
                ref:
                  type: string
                  description: Reference to quote to support.
        example:
          error: server_error
          error_description: >-
            Something went wrong on our side. Please try again shortly, or contact support with
            reference a1b2c3d4e5f6.
          ref: a1b2c3d4e5f6
```

**curl**

```bash
curl -X POST "https://omnidim.io/api/v1/phone_number/release" \
  -H "Authorization: Bearer $OMNIDIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phone_number": "+15551234567"
}'
```

Releasing gives the number up and stops its rental, so it is not charged at the
next renewal.

More in [Buy a number over the API](/docs/buy-a-number-api).