---
title: "Market API: Premium-Rate Services"
section: "Market API"
order: 270
excerpt: "Protected French premium-rate number lookup: HTTPS bearer access, number formats, response fields, and error handling."
---

### GET /api/v1/market/premium-rate-service

Look up one French number using a dedicated machine bearer credential over HTTPS. Successes and failures carry `Cache-Control: private, no-store`. All tariff examples are synthetic.

**Auth required:** Yes — dedicated machine bearer credential over HTTPS.

Endpoint: `https://www.bluerocktel.com/api/v1/market/premium-rate-service`

This protected route looks up one French number per request. It has no bulk export or public tariff browser. Access to public market catalogues does not grant access to this lookup. The examples below are synthetic and do not describe live tariffs or guarantee that an example number exists in the catalogue.

## Authentication and rotation

Send `Authorization: Bearer YOUR_API_TOKEN` and `Accept: application/json`. Obtain a dedicated credential through your operator; never put credentials in the URL or query string. HTTP requests receive 403 without a redirect. Successes and failures carry `Cache-Control: private, no-store`.

Operators provision a new current credential and retain the previous credential only for a deliberate transition period. Update the client, verify access, then have the operator revoke the previous credential. The overlap does not expire automatically. Keep credentials in deployment secrets and out of logs, source control, and documentation. Operators must reload application configuration and long-lived workers when changing credentials.

The default configurable limit is **60 requests per 60-second window per credential**. Authenticated requests count even when number validation fails. Current and previous credentials have separate quotas; moving a credential to the previous slot preserves its quota. On 429, wait for the `Retry-After` header (seconds) before retrying.

## Number formats

The required `number` query parameter is a string. Keep leading zeroes. Supported forms are:

| Form | Synthetic example | Canonical result |
|---|---|---|
| Ten-digit national number, `0` then a nonzero digit and eight digits | `0890123456` | `0033890123456` |
| `+33` followed by nine digits, first digit nonzero | `+33890123456` | `0033890123456` |
| `33` followed by the same nine digits | `33890123456` | `0033890123456` |
| `0033` followed by the same nine digits | `0033890123456` | `0033890123456` |
| Four-digit short number | `3618` | `00333618` |
| `0033` followed by four digits | `00333618` | `00333618` |

All digits must be ASCII. Whitespace, separators, arrays, unsupported lengths, and other country prefixes are rejected. Short numbers do not support `+33` or bare `33` prefixes. Syntactic acceptance does not establish catalogue coverage or number allocation.

URL-encode the plus sign as `%2B`: `?number=%2B33890123456`. An unescaped `+` in a query becomes a space and is rejected. For example, let curl encode the value:

```bash
curl --get 'https://www.bluerocktel.com/api/v1/market/premium-rate-service' \
  --data-urlencode 'number=+33890123456' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json'
```

## Successful response

**Response 200:** One record in the market envelope. This is a synthetic example.

```json
{
  "api_version": "1",
  "catalogue": "premium-rate-services",
  "generated_at": "2026-09-21T12:00:00Z",
  "count": 1,
  "data": [
    {
      "number": "0033890123456",
      "connection_price_with_tax": 1.25,
      "minute_price_with_tax": 0.07,
      "charge_communication": 1,
      "service_name": "Synthetic example service",
      "country": "fr"
    }
  ]
}
```

| Envelope field | JSON type | Meaning |
|---|---|---|
| `api_version` | string | Always `"1"`. |
| `catalogue` | string | Always `"premium-rate-services"`. |
| `generated_at` | string | UTC ISO 8601 response time. |
| `count` | integer | `1` on success; `0` for a valid unknown number (404). |
| `data` | array | One record on success; empty for 404. |

`generated_at` is response time, not tariff freshness. No tariff effective date or refresh timestamp is exposed. Operators must monitor tariff freshness through their controlled refresh workflow; a recent response timestamp does not demonstrate a recent tariff update.

Each record contains exactly these six fields:

| Record field | JSON type | Meaning |
|---|---|---|
| `number` | string | Canonical `0033` number: 13 characters for long numbers, 8 for short numbers. |
| `connection_price_with_tax` | number | Nonnegative service connection price including tax. |
| `minute_price_with_tax` | number | Nonnegative service price per minute including tax. |
| `charge_communication` | integer | `0` or `1`; `1` indicates a separate communication charge applies. |
| `service_name` | string | Service label, or `""` when missing; never null. |
| `country` | string | Always `"fr"`. |

Prices are JSON numbers, not quoted decimal strings. Use decimal-aware parsing when exact monetary arithmetic is required. No source, provenance, supplier code, or import timestamp is returned.

## Shortcut semantics

After normalization, these rules run before catalogue lookup and take precedence over catalogue entries:

| Canonical number rule | Both service prices | `charge_communication` |
|---|---|---|
| Exactly 13 characters, prefix `0033800` through `0033805` | `0` | `0` |
| Exactly 13 characters, prefix `0033806` through `0033809` | `0` | `1` |
| Exactly 8 characters, prefix `003330` or `003331` | `0` | `0` |

Shortcut records have an empty `service_name` and country `fr`. Zero service prices with flag `1` do not mean the whole call is free. These shortcuts work without a catalogue lookup, including when the catalogue is unavailable. Other valid numbers require the catalogue; prefix matching alone never overrides the exact length requirements.

## Errors

**Response 400:** Missing or malformed `number`.

```json
{"message":"Invalid number."}
```

**Response 401:** Missing or invalid bearer credential. Includes `WWW-Authenticate: Bearer`.

```json
{"message":"Unauthenticated."}
```

**Response 403:** HTTPS is required.

```json
{"message":"HTTPS required."}
```

**Response 404:** A valid number is absent from the available, complete catalogue. This synthetic example uses the same envelope as success, with no record.

```json
{
  "api_version": "1",
  "catalogue": "premium-rate-services",
  "generated_at": "2026-09-21T12:00:00Z",
  "count": 0,
  "data": []
}
```

**Response 429:** Credential rate limit exceeded. Includes `Retry-After` in seconds.

```json
{"message":"Too many requests."}
```

**Response 503:** Required lookup artifacts are missing, corrupt, or unavailable, or access infrastructure is unavailable. This does not mean the number is absent.

```json
{"message":"Service unavailable."}
```

Authentication and rate limiting run before number lookup. Apart from 404, the listed errors use a `message` string object, not the success envelope. Handle the HTTP status before reading `data[0]`; use bounded retries for temporary failures and never substitute a zero tariff for 404 or 503.

## Migrating older consumers

Old bare-record consumers require a deliberate adapter, not just a URL change. Configure the website endpoint and HTTPS bearer access, check the status and envelope, and read the record from `data[0]` only on 200 with `count: 1`. Preserve number strings and account for numeric price fields, integer communication flags, empty labels, timeouts, and the distinct error responses above. This endpoint provides neither a legacy bare-record mode nor a bulk download.