---
title: "Request a country"
method: POST
path: "/public/country-requests"
tags: ["Countries"]
---

# Request a country

`POST /public/country-requests`

## Request

- Base URL: `https://api.baseray.ai/v1`
- URL: `https://api.baseray.ai/v1/public/country-requests`
- Auth: none required

Asks for baseray in a country it does not cover yet, for a person who agrees to be emailed when it does. One request per address and country: asking again changes nothing and answers the same, so the answer never tells whether an address had asked before. A country baseray already covers answers `live` and stores nothing. The address is never shown or shared; product analytics count the country only.

## Request body

- CountryRequest
  - `country` string, required: The country asked for: an ISO 3166-1 alpha-2 code, such as `DE`.
  - `email` string, email, required: Where to write when baseray covers the country. Compared in lower case: the same address asks for a country once.
  - `consent` true, required: Must be `true`: the person agrees to be emailed about this country. Kept for 24 months at most and deleted on request (privacy@baseray.ai).
  - `company` string, nullable: The person's company, up to 200 characters.
  - `use_case` 'solar_prospecting' | 'heating_upgrades' | 'energy_efficiency' | 'insurance_underwriting' | 'real_estate_prospecting' | 'market_research' | 'other' | 'null', nullable: What they want the buildings for.
  - `locale` string, nullable: The language to write back in, as a two-letter code (`en`, `ro`, `cs`).
  - `attribution` object, nullable: Where the person came from before asking (first touch), as the website carries it.
    - `utm_source` string, nullable: Campaign source, up to 200 characters.
    - `utm_medium` string, nullable: Campaign medium, up to 200 characters.
    - `utm_campaign` string, nullable: Campaign name, up to 200 characters.
    - `utm_content` string, nullable: Campaign content, up to 200 characters.
    - `utm_term` string, nullable: Campaign term, up to 200 characters.
    - `gclid` string, nullable: Google Ads click id, up to 200 characters.
    - `referrer_host` string, nullable: Host of the site that sent the person, up to 255 characters.
    - `landing_path` string, nullable: The first page the person saw, up to 500 characters.

## Response `200`

baseray already covers this country; nothing was stored.

- CountryRequestReceipt: The answer to a country request.
  - `status` 'received' | 'live', required: `received`: the request is on the list (also when this address had asked before). `live`: baseray already covers the country; nothing was stored.
  - `country` string, required: The country asked for, upper case.

## Other responses

- `202`: Received.
- `400`: A field is missing, malformed or unknown (`invalid_parameter`); `parameter` names it.
- `429`: Too many country requests from this visitor in an hour (`rate_limited`); retry after `Retry-After` seconds.

---

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