---
title: "Number offers"
method: GET
path: "/v1/numbers/offers"
tags: ["Owner"]
---

# Number offers

`GET /v1/numbers/offers`

## Request

- Base URL: `https://api.vicem.ai`
- URL: `https://api.vicem.ai/v1/numbers/offers`
- Auth: HTTP bearer

## Query parameters

- `home` string

## Response `200`

OK

- NumberOffers
  - `home` string, required
  - `recommended` NumberOffer, required
    - `country` string, required
    - `provider` 'telnyx' | 'didww', required
    - `numberType` 'local' | 'national' | 'mobile', required
    - `instant` boolean, required
    - `status` 'instant' | 'form' | 'documents', required
    - `needs` NeedKind[], required
    - `reviewDays` object, nullable, required
      - `typical` number, required
      - `max` number, required
    - `monthlyUsd` number, nullable, required
    - `setupUsd` number, nullable
    - `sms` boolean, required
    - `forwardCost` 'domestic' | 'international' | 'unknown', required
  - `instant` NumberOffer[], required
    - `country` string, required
    - `provider` 'telnyx' | 'didww', required
    - `numberType` 'local' | 'national' | 'mobile', required
    - `instant` boolean, required
    - `status` 'instant' | 'form' | 'documents', required
    - `needs` NeedKind[], required
    - `reviewDays` object, nullable, required
      - `typical` number, required
      - `max` number, required
    - `monthlyUsd` number, nullable, required
    - `setupUsd` number, nullable
    - `sms` boolean, required
    - `forwardCost` 'domestic' | 'international' | 'unknown', required
  - `documents` NumberOffer[], required
    - `country` string, required
    - `provider` 'telnyx' | 'didww', required
    - `numberType` 'local' | 'national' | 'mobile', required
    - `instant` boolean, required
    - `status` 'instant' | 'form' | 'documents', required
    - `needs` NeedKind[], required
    - `reviewDays` object, nullable, required
      - `typical` number, required
      - `max` number, required
    - `monthlyUsd` number, nullable, required
    - `setupUsd` number, nullable
    - `sms` boolean, required
    - `forwardCost` 'domestic' | 'international' | 'unknown', required
  - `interimDefault` string, required
  - `held` object[]
    - `country` string, required
    - `e164` string, required

## Other responses

- `400`: Invalid request (body not JSON, or schema validation failed).
- `401`: Missing, expired or invalid bearer token.
- `500`: Unexpected server error (reported to Sentry).

---

[API](https://skmtc.dev/vicem/apis/vicem-api.md) · [All operations](https://skmtc.dev/vicem/apis/vicem-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vicem/apis/vicem-api/revisions/9efcec07e5f4?raw)