Deep integration overview

A deep integration allows your end users to book and ride Voi vehicles directly through your app. This page covers the concepts; the full, interactive endpoint documentation lives in the API reference, where you can paste your API key and try every request live.

API contract

Regardless of new features launched in the future, Voi commits to supporting the current feature-set for partners and not perform breaking changes to this version of the API, though we might add new endpoints. We expect you to cache cacheable data. All major updates are communicated to active partners via email before they are implemented.

Development

For a broader description of the integration process, see the deep integration checklist.

Test your application against our staging environment. In staging, we provide virtual scooters and available zone types, located in Berlin. Staging differs from production in these ways:

• Unlocking or locking a vehicle always responds with success, even if a rental is already running.
• The vehicle location does not change even if you provide an end-ride location.
• Zones and vehicles are spread over a much larger area than real vehicles.

Going live

Once development is done, reach out to our point of contact for engineering to receive production keys for the cities you operate in, together with your cities' zone IDs. Test the integration in closed beta before giving access to all your users.

Rate limit

There is a default rate limit of 4000 requests per minute (sum of all requests). Voi follows industry best practices by returning an HTTP 429 response when the rate limit is exceeded. If you need a higher limit, contact our engineering support.

Environments

Environment	Base URL
Staging	https://partners.stage.voiapp.io
Production	https://partners.voiapp.io

Authentication

All API endpoints are protected with API-key authentication. Include your API key in the X-Access-Token request header on every request:

curl "https://partners.voiapp.io/v1/zone/info" \
  -H "X-Access-Token: $API_KEY"

Key	Value
X-Access-Token	your-api-key

Contact our engineering support to receive your API key.

:::warning Legacy authentication (deprecated)

The previous token-based authentication method using the X-Auth-Token header is deprecated. Existing tokens will continue to work but will not be renewed upon expiration. Please migrate to the API-key method described above.

:::

A typical journey

1. Register the user — POST /v1/user/register
2. Discover vehicles in a zone — GET /v1/vehicles
3. Start a rental — POST /v1/rental/start
4. Poll the rental while riding — GET /v1/rental/{id}
5. End the rental and charge the user — POST /v1/rental/{rentalId}/end

Pricing

The cost of renting a Voi can differ based on where the vehicle is located and what time it is. When the user starts the ride, we commit to the price presented at that time. Some exceptions can cause the price to change. The actual price is always returned when ending the ride, so you can charge the end user correctly. All amounts are returned in minor units (e.g. 1213 = €12.13). See Payments for fines, refunds and invoicing.

GDPR requests

The right to be forgotten and other GDPR requests require us to go through all our internal systems manually. Such requests are handled by contacting customer support.

Endpoints not planned

For clarity, these endpoints are intentionally not available. We will notify all partners if this changes:

• It is not possible to delete users programmatically (ask users to contact customer support for the right to be forgotten).
• Lock and reserve are not part of the API, as the feature is not widely used.
• Payment methods are not available, since we do not support payment methods in the partner app.
• We do not provide a way to give a reason for the absence of a parking photo.
• We do not provide callbacks or webhooks — all interactions are pull-based.