Field catalogue and privacy allowlist

The reviewed scopes of an integration are the outer boundary. An active user grant may reduce that set further. Unknown fields are rejected on ingest and removed again at operator egress. A field appearing in BOT's internal data does not make it part of this contract.

The downloadable JSON Schemas are normative for JSON types and shape. This catalog explains meaning and privacy boundaries. Fields can be omitted when BOT has not received an allowed value; an explicit null means the allowed value is currently unknown. Consumers must ignore newly documented optional fields but must not accept unknown fields when validating uploads or generating webhook payloads.

All date-times are ISO 8601/RFC 3339 UTC values and all date-only fields use YYYY-MM-DD. Country values are upper-case ISO 3166-1 alpha-2 codes. Resource identity always comes from the envelope's resource.id; it is random and scoped to one integration. Do not require or derive an identifier inside data.

Some compatible upload versions can represent configuration, location, dates, or milestones either as top-level fields or in the correspondingly named nested object. Consumers must support the forms admitted by the JSON Schema. The v1 contract does not assign a general precedence to conflicting duplicates, so do not silently merge contradictory values. expected_delivery is the authoritative human-readable delivery-window text; parsed start/end dates remain separate, nullable interpretations.

Order snapshot#

The orders.read scope may expose:

• identity-neutral vehicle/order description: model, variant, factory, factory_code, and unique option_codes (the codes are configuration data, never a VIN or provider identifier);
• resolved configuration: color, wheels, interior, autopilot, and nullable boolean tow_hitch (compatible top-level fields can also occur);
• delivery_center and two-letter country/country_code, either top-level or in location where supported;
• order_date, reservation_date, order_booked_date, delivery_appointment_date, expected_start_date, expected_end_date, and authoritative text expected_delivery, plus the non-personal availability milestone parts_catalog_available_on, either top-level or in dates where supported;
• nullable milestone flags/timestamps: vin_assigned, vin_assigned_on, vehicle_built, vehicle_built_on, in_production_at, ready_for_pickup_at, in_transit_at, and date-only delivered_date, either top-level or in milestones;
• status and last_delivery_window_change_at.

Individual status is a forward-compatible source value, not the closed set used by the statistics endpoint. Do not fail an entire sync because a new status string appears.

With the separately reviewed shipping.read scope, an actively granted order may additionally contain minimized vessel, voyage, loading_port, destination_port, estimated_departure_at, estimated_arrival_at, and up to 2,000 shipping events. An event can contain event_type, port, country, occurred_at, observed_at, and status. Shipping never contains a VIN or serial number. Without the effective shipping.read grant, the entire object is removed even if it exists internally.

Order history#

orders.history.read exposes an append-only, cursor-paged sequence. Each item contains sequence, allowlisted field, operation, minimized old/new value, event_at, observed_at, and data_quality. history_complete=false means the app has not yet uploaded and closed the full initial history. The marker changes only after the explicit completion operation.

sequence is monotonic within one resource history, not across resources. event_at is the time attributed to the underlying change; observed_at is when BOT observed/received it. data_quality is descriptive and forward-compatible. The allowed operations are set, unset, append, and replace. Apply pages in sequence order, retain null as a meaningful old/new value, and never claim the history is complete merely because has_more=false while history_complete=false.

The changed field is restricted to a path from the corresponding allowlisted snapshot. Array changes may be indexed without exposing an identity: for example, option_codes[0] changes exactly one option code and shipping.events[3].status changes one permitted shipping-event value. Both bracket indexes and their canonical dot-index equivalent can be consumed. Indexes range from 0 through 1999. Unknown paths and paths to VINs, true order numbers or any other forbidden data are rejected at upload and removed again at egress. option_codes and every indexed option-code history change are available for both orders and stock vehicles when the corresponding snapshot and history scopes are active.

Stock vehicle snapshot and history#

For an individually selected stock vehicle, vehicles.read may expose:

• identity-neutral description: model, variant, factory, factory_code, unique option_codes, resolved configuration, car_type, trim_badging, wheel_type, spoiler_type, exterior_color, driver_assist, headlamp_type, rear_drive_unit, and efficiency_package;
• operating/feature state: state, in_service, has_air_suspension, has_seat_cooling, and smart_summon_available;
• battery/range: battery_level, usable_battery_level, battery_range, battery_range_km, ideal_battery_range, ideal_battery_range_km, estimated_battery_range, and est_battery_range_km;
• charging: charging_state, charge_rate, charger_power, charge_power_kw, charger_voltage, charger_phases, charger_actual_current, charge_limit_soc, time_to_full_charge, charge_energy_added, charge_miles_added_rated, conn_charge_cable, charge_port_type, charge_port_latch, and charge_port_color;
• distance/software/tyres: odometer, odometer_km, software_version, software_update_version, and tpms_pressure_fl/fr/rl/rr;
• minimized battery hints: battery_pack_hint, battery_family_hint, battery_capacity_kwh_hint, battery_detection_source, and battery_detection_confidence;
• observation times: last_updated_at and observed_at.

Names containing _km, _kw, or _kwh carry kilometres, kilowatts, or kilowatt-hours respectively. Battery/SOC percentages are in the inclusive 0–100 range; battery_detection_confidence is 0–1. The v1 schema does not make a unit guarantee for legacy unsuffixed numeric fields such as battery_range, odometer, charge_rate, time_to_full_charge, or tyre pressure. Prefer the explicitly suffixed form when present and do not invent a conversion for an unsuffixed value.

vehicles.history.read uses the same history envelope as order history. Identical received states are deduplicated; an actual allowlisted change is not discarded. Vehicle snapshot and history access are separate scopes.

option_codes is deliberately part of the documented order and vehicle contract so an authorized integration can resolve configurations and build useful aggregate analyses. It is not available from a resource the user did not select, and it never weakens the separate statistics opt-in or minimum-cell rules.

Scope combinations#

• orders.read is required for order snapshots/sync upserts.
• orders.history.read is required for order history and does not add shipping.
• shipping.read only adds the minimized shipping subtree to an already readable, actively granted order.
• vehicles.read is required for selected stock-vehicle snapshots/sync upserts.
• vehicles.history.read is required for selected stock-vehicle history.
• statistics.orders.read returns only fixed preaggregated generations; it does not grant any individual order.
• revocations.ack permits deletion acknowledgements and grants no read access.

Order statistics vocabulary#

Every returned cell contains dimensions and value. The metric name is the key containing the cell array. Cells below the minimum cohort size are omitted, so breakdowns must never be summed to infer a total.

| Metric | Dimension keys | Value | |---|---|---| | orders_total | country | Integer count of all opted-in orders in the country | | by_model_variant_status | country, model, variant, status | Integer count | | vin_assigned | country | Integer count | | vehicle_built | country | Integer count | | delivery_within_30_days | country | Integer count | | delivery_within_60_days | country | Integer count | | average_order_age_days | country | Number of days | | daily_vin_assignments | country, date | Integer count | | daily_builds | country, date | Integer count | | by_delivery_center | country, delivery_center | Integer count | | by_color | country, color | Integer count | | lead_time_order_to_vin_days | country, percentile | Number of days | | lead_time_vin_to_delivery_days | country, percentile | Number of days |

status is one of open, booked, in_production, ready_for_pickup, or in_transit; percentile is p25, p50, or p75; and date is an ISO YYYY-MM-DD calendar date. orders_total is evaluated directly against the same minimum cell size and does not depend on which breakdown cells survive suppression.

The effective scopes returned by GET /v1/capabilities are the maximum for that certificate/environment. A user's resource grant can narrow them further.

Always forbidden#

The API never exposes real VINs or order numbers; BOT/Tesla account identifiers; names, email, phone, address or other contact data; financing, payment or profile data; Tesla IDs, access tokens or credentials; raw Tesla/EPC responses; application version/platform; parts/equipment summaries in the reference profile; GPS/calendar/vehicle name; or door, window, lock and other presence/security state. Forbidden values are excluded from snapshots, histories, aggregates, webhooks, logs and error documents.

The random connection_id, ord_* and veh_* values are scoped to one integration and cannot be correlated with another integration's identifiers. They are still authorization-bound application data: do not expose them in URLs, analytics or logs beyond what the integration needs to operate.