> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a zone > Creates a zone in one country: the whole country, or part of it defined by states, postal codes or a GeoJSON MultiPolygon. Membership is resolved by Flatpeak and re-evaluated continuously; Resolving a new zone can take time, so the response returns `device_count` as `null`. `zone.membership.update` fires when the count is ready, and afterwards whenever devices join or leave. ## OpenAPI ````yaml fleet-api/reference/flatpeak-api-spec-fleet.json POST /zones openapi: 3.0.3 info: description: >- The Flatpeak Fleet API. VPP operators use it to enroll, dispatch and settle OEM device fleets. ## Authentication Exchange your `account_id` and `secret_key` for a bearer token at `POST /auth/tokens` with basic auth. Send it as `Authorization: Bearer ` on every request. ## Base URL `https://fleet-api.flatpeak.com` ## Pagination Lists return `data`, `next_cursor` and `url`. Pass `next_cursor` as `cursor` until it is `null`. A cursor is opaque and bound to the endpoint and query parameters that issued it. ## Errors Every non-2xx response carries `object`, `type`, `code` and `message`. Branch on `code`. ## Money and energy Money is a decimal number paired with a `currency_code` (ISO 4217). Power is in kW and energy in kWh. Positive is import, negative is export. ## Live and test `live_mode` marks live or test data. version: 2027-01-01.busbar title: Flatpeak Fleet API termsOfService: https://flatpeak.com/legal contact: name: Technical Support email: support@flatpeak.com url: https://flatpeak.com/contact license: name: Apache 2.0 url: https://flatpeak.com/legal servers: - url: https://fleet-api.flatpeak.com security: - bearerAuth: [] tags: - name: Authentication description: >- Exchange your account credentials for a bearer token to authenticate API requests. - name: Connect description: >- Create and retrieve Connect sessions for onboarding customers through your own app. - name: OEMs description: List and retrieve the OEMs whose devices your fleet can reach. - name: Devices description: >- Retrieve, list and update the devices connected to your account, and read their consent history and shared settings. - name: Locations description: >- Read the location a device sits behind: its timezone, currency, metering and your devices there. - name: Dispatch description: Submit plans to devices on managed tariffs and read the dispatch timeline. - name: Telemetry description: Read device state, device meter records and location meter records. - name: Tariffs description: Create, retrieve, delete, and list tariffs. - name: Events description: Retrieve and list account events. - name: VPP Programs description: >- Define and manage VPP programs: the commercial terms devices enroll under, and their live state. - name: Groups description: >- Named collections of devices for bulk dispatch and aggregated reads. OEMs see them read-only as [groups](/energy-api/reference/groups/list) on the Energy API. - name: Zones description: >- Network areas resolved to devices by Flatpeak, for locational eligibility and grouping without handling addresses. - name: Exports description: >- Package settlement evidence, consent records and enrollment registers as downloadable files. - name: Rewards description: >- The reward ledger: entries accrue from delivery, you approve them, pay the customers and mark them paid. - name: VPP Enrollments description: Track and act on device enrollments across your programs. - name: VPP Events description: >- Commit market activations: create an event for a group, then read its state and its devices' results. externalDocs: description: Documentation url: https://docs.flatpeak.com paths: /zones: parameters: [] post: tags: - Zones summary: Create a zone description: >- Creates a zone in one country: the whole country, or part of it defined by states, postal codes or a GeoJSON MultiPolygon. Membership is resolved by Flatpeak and re-evaluated continuously; Resolving a new zone can take time, so the response returns `device_count` as `null`. `zone.membership.update` fires when the count is ready, and afterwards whenever devices join or leave. operationId: create-a-zone parameters: [] requestBody: $ref: '#/components/requestBodies/ZoneCreate' responses: '201': $ref: '#/components/responses/ZoneResolving' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '422': $ref: '#/components/responses/422' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/503' components: requestBodies: ZoneCreate: description: Zone payload. required: true content: application/json: schema: $ref: '#/components/schemas/ZoneCreate' responses: '400': description: >- 400 Bad Request: the request was malformed or a required field is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: '401 Unauthorized: authentication credentials are missing or invalid.' content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: '403 Forbidden: you do not have permission to access this resource.' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '404 Not Found: the requested resource does not exist.' content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- 422 Unprocessable Entity: the request is well-formed but cannot be processed, for example missing required data. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '429 Too Many Requests: the rate limit has been exceeded.' content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: >- 500 Internal Server Error: an unexpected error occurred. Safe to retry with backoff. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- 503 Service Unavailable: the service is temporarily down for maintenance. Retry after the indicated delay. content: application/json: schema: $ref: '#/components/schemas/Error' ZoneResolving: description: >- Zone response. `device_count` is `null` while membership is being resolved. content: application/json: schema: $ref: '#/components/schemas/Zone' example: id: zon_9b3c5d7e1f2a4b6c8d0e2f4a object: zone live_mode: true name: NGED Bristol constraint zone definition: country_code: GB postal_codes: - BS1 - BS2 - BS3 device_count: null time_created: '2026-08-12T09:30:00Z' account_id: acc_649d465ede6a785d2fa5f905 schemas: ZoneCreate: title: ZoneCreate type: object description: Zone create payload. properties: name: type: string example: NGED Bristol constraint zone description: Zone name, for your own reference. definition: type: object description: >- The zone area: a country, narrowed by at most one of `states`, `postal_codes` or `multipolygon`. With none of the three, the zone is the whole country. properties: country_code: type: string pattern: ^[A-Z]{2}$ description: >- Country the zone is in, as a two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code. Required: a postal code or a state has no meaning without it. example: GB states: type: array items: type: string pattern: ^[A-Z0-9]{1,3}$ description: >- States or provinces in `country_code`, as the code after the hyphen in ISO 3166-2: `CA` for California, `NSW` for New South Wales. Matched against the `state` of the device's address, which carries these codes for Australia, Canada and the US. example: - CA postal_codes: type: array items: type: string description: >- Postal codes or prefixes in `country_code`: `BS1` matches every postcode under it. Where codes are coarse, prefer `multipolygon`. example: - BS1 - BS2 - BS3 multipolygon: type: object description: >- GeoJSON MultiPolygon. A single area is a MultiPolygon with one polygon; disjoint areas, for example a constraint zone with two pockets, are one zone rather than several. example: type: MultiPolygon coordinates: - - - - -2.627418 - 51.438902 - - -2.589734 - 51.431256 - - -2.553127 - 51.440671 - - -2.541905 - 51.458394 - - -2.556283 - 51.474816 - - -2.592046 - 51.481237 - - -2.624861 - 51.470529 - - -2.636152 - 51.453318 - - -2.627418 - 51.438902 required: - country_code example: country_code: GB postal_codes: - BS1 - BS2 - BS3 required: - name - definition Zone: title: Zone type: object description: >- An area in one country: the whole country, or part of it defined by states, postal codes or a GeoJSON MultiPolygon. Flatpeak resolves membership from enrollment addresses; you receive counts and device IDs, never addresses. `zone.membership.update` fires on changes. properties: id: type: string description: Flatpeak Zone ID. example: zon_9b3c5d7e1f2a4b6c8d0e2f4a object: type: string example: zone description: Object type, `zone`. enum: - zone live_mode: type: boolean description: '`true` for live data, `false` for test data.' example: true name: type: string example: NGED Bristol constraint zone description: Zone name, for your own reference. definition: type: object description: >- The zone area: a country, narrowed by at most one of `states`, `postal_codes` or `multipolygon`. With none of the three, the zone is the whole country. properties: country_code: type: string pattern: ^[A-Z]{2}$ description: >- Country the zone is in, as a two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code. Required: a postal code or a state has no meaning without it. example: GB states: type: array items: type: string pattern: ^[A-Z0-9]{1,3}$ description: >- States or provinces in `country_code`, as the code after the hyphen in ISO 3166-2: `CA` for California, `NSW` for New South Wales. Matched against the `state` of the device's address, which carries these codes for Australia, Canada and the US. example: - CA postal_codes: type: array items: type: string description: >- Postal codes or prefixes in `country_code`: `BS1` matches every postcode under it. Where codes are coarse, prefer `multipolygon`. example: - BS1 - BS2 - BS3 multipolygon: type: object description: >- GeoJSON MultiPolygon. A single area is a MultiPolygon with one polygon; disjoint areas, for example a constraint zone with two pockets, are one zone rather than several. example: type: MultiPolygon coordinates: - - - - -2.627418 - 51.438902 - - -2.589734 - 51.431256 - - -2.553127 - 51.440671 - - -2.541905 - 51.458394 - - -2.556283 - 51.474816 - - -2.592046 - 51.481237 - - -2.624861 - 51.470529 - - -2.636152 - 51.453318 - - -2.627418 - 51.438902 required: - country_code example: country_code: GB postal_codes: - BS1 - BS2 - BS3 device_count: type: integer readOnly: true description: >- Devices resolved into the zone. `null` while Flatpeak is still resolving membership, which happens after the zone is created and after its `definition` changes. example: 214 nullable: true time_created: type: string format: date-time description: Time when the object was created, in UTC. example: '2026-08-12T09:30:00Z' account_id: type: string description: Flatpeak Account ID of the operator that owns the zone. example: acc_649d465ede6a785d2fa5f905 required: - id - object - live_mode - name - definition - device_count - time_created - account_id Error: type: object description: Standard error envelope returned by every non-2xx response. required: - object - type - code - message properties: object: type: string enum: - error default: error description: Object type. type: type: string description: High-level error category. example: invalid_request code: type: string description: Machine-readable error code, safe to branch on. example: access_denied message: type: string description: Human-readable description of the error. example: The requested resource could not be found. context: type: string description: Optional originating context, for example `api.price_get`. example: api.price_get live_mode: type: boolean description: Whether the error occurred against live or test data. time_created: type: string format: date-time description: Time the error was generated (RFC 3339). example: '2026-01-01T00:00:00Z' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Authenticate with the `bearer_token` obtained from the [authentication](/fleet-api/reference/authentication) endpoint. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.