Create a vehicle

curl --request POST \
  --url https://api.vehicle.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/vehicles \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Delivery van 07",
  "licensePlate": "BRA2E19",
  "make": "Fiat",
  "model": "Fiorino",
  "year": 2023,
  "shared": [
    {
      "id": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
      "role": "OWNER",
      "firstName": "Mariana",
      "lastName": "Costa",
      "email": "mariana.costa@acme.com.br"
    }
  ],
  "customFields": {
    "cost-center": "CC-1020"
  }
}
'

import requests

url = "https://api.vehicle.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/vehicles"

payload = {
    "name": "Delivery van 07",
    "licensePlate": "BRA2E19",
    "make": "Fiat",
    "model": "Fiorino",
    "year": 2023,
    "shared": [
        {
            "id": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
            "role": "OWNER",
            "firstName": "Mariana",
            "lastName": "Costa",
            "email": "mariana.costa@acme.com.br"
        }
    ],
    "customFields": { "cost-center": "CC-1020" }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Delivery van 07',
    licensePlate: 'BRA2E19',
    make: 'Fiat',
    model: 'Fiorino',
    year: 2023,
    shared: [
      {
        id: 'e3553bc1-5e20-4e17-b22a-a796fda0aa99',
        role: 'OWNER',
        firstName: 'Mariana',
        lastName: 'Costa',
        email: 'mariana.costa@acme.com.br'
      }
    ],
    customFields: {'cost-center': 'CC-1020'}
  })
};

fetch('https://api.vehicle.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/vehicles', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vehicle.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/vehicles",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Delivery van 07',
    'licensePlate' => 'BRA2E19',
    'make' => 'Fiat',
    'model' => 'Fiorino',
    'year' => 2023,
    'shared' => [
        [
                'id' => 'e3553bc1-5e20-4e17-b22a-a796fda0aa99',
                'role' => 'OWNER',
                'firstName' => 'Mariana',
                'lastName' => 'Costa',
                'email' => 'mariana.costa@acme.com.br'
        ]
    ],
    'customFields' => [
        'cost-center' => 'CC-1020'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vehicle.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/vehicles"

	payload := strings.NewReader("{\n  \"name\": \"Delivery van 07\",\n  \"licensePlate\": \"BRA2E19\",\n  \"make\": \"Fiat\",\n  \"model\": \"Fiorino\",\n  \"year\": 2023,\n  \"shared\": [\n    {\n      \"id\": \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\",\n      \"role\": \"OWNER\",\n      \"firstName\": \"Mariana\",\n      \"lastName\": \"Costa\",\n      \"email\": \"mariana.costa@acme.com.br\"\n    }\n  ],\n  \"customFields\": {\n    \"cost-center\": \"CC-1020\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vehicle.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/vehicles")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Delivery van 07\",\n  \"licensePlate\": \"BRA2E19\",\n  \"make\": \"Fiat\",\n  \"model\": \"Fiorino\",\n  \"year\": 2023,\n  \"shared\": [\n    {\n      \"id\": \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\",\n      \"role\": \"OWNER\",\n      \"firstName\": \"Mariana\",\n      \"lastName\": \"Costa\",\n      \"email\": \"mariana.costa@acme.com.br\"\n    }\n  ],\n  \"customFields\": {\n    \"cost-center\": \"CC-1020\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vehicle.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/vehicles")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Delivery van 07\",\n  \"licensePlate\": \"BRA2E19\",\n  \"make\": \"Fiat\",\n  \"model\": \"Fiorino\",\n  \"year\": 2023,\n  \"shared\": [\n    {\n      \"id\": \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\",\n      \"role\": \"OWNER\",\n      \"firstName\": \"Mariana\",\n      \"lastName\": \"Costa\",\n      \"email\": \"mariana.costa@acme.com.br\"\n    }\n  ],\n  \"customFields\": {\n    \"cost-center\": \"CC-1020\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "6710b8e4c9e77b0012a4d6f1",
  "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
  "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
  "name": "Delivery van 07",
  "licensePlate": "BRA2E19",
  "make": "Fiat",
  "model": "Fiorino",
  "year": 2023,
  "status": "ACTIVE",
  "external": {
    "walletId": "6710b8e4c9e77b0012a4d6f3",
    "accountId": "66f2a1c7b4d3e80012c9a0b4"
  },
  "customFields": {
    "cost-center": "CC-1020"
  },
  "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
  "updatedBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
  "createdAt": "2026-10-17T13:45:12.000Z",
  "updatedAt": "2026-10-17T13:45:12.000Z"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "VEHICLE_ADMIN_REQUIRED",
  "origin": "VEHICLE",
  "message": "Organization admin required"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "BAD_REQUEST",
  "origin": "VEHICLE",
  "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
  "fields": [
    {
      "field": "name",
      "message": "Invalid input: expected string, received undefined",
      "code": "NAME_REQUIRED"
    }
  ]
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "VEHICLE_BANKING_ACCOUNT_UNAVAILABLE",
  "origin": "VEHICLE",
  "message": "No banking account is provisioned for this organization"
}

POST

realms

{realmId}

organizations

{organizationId}

vehicles

Create a vehicle

curl --request POST \
  --url https://api.vehicle.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/vehicles \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Delivery van 07",
  "licensePlate": "BRA2E19",
  "make": "Fiat",
  "model": "Fiorino",
  "year": 2023,
  "shared": [
    {
      "id": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
      "role": "OWNER",
      "firstName": "Mariana",
      "lastName": "Costa",
      "email": "mariana.costa@acme.com.br"
    }
  ],
  "customFields": {
    "cost-center": "CC-1020"
  }
}
'

import requests

url = "https://api.vehicle.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/vehicles"

payload = {
    "name": "Delivery van 07",
    "licensePlate": "BRA2E19",
    "make": "Fiat",
    "model": "Fiorino",
    "year": 2023,
    "shared": [
        {
            "id": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
            "role": "OWNER",
            "firstName": "Mariana",
            "lastName": "Costa",
            "email": "mariana.costa@acme.com.br"
        }
    ],
    "customFields": { "cost-center": "CC-1020" }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Delivery van 07',
    licensePlate: 'BRA2E19',
    make: 'Fiat',
    model: 'Fiorino',
    year: 2023,
    shared: [
      {
        id: 'e3553bc1-5e20-4e17-b22a-a796fda0aa99',
        role: 'OWNER',
        firstName: 'Mariana',
        lastName: 'Costa',
        email: 'mariana.costa@acme.com.br'
      }
    ],
    customFields: {'cost-center': 'CC-1020'}
  })
};

fetch('https://api.vehicle.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/vehicles', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vehicle.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/vehicles",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Delivery van 07',
    'licensePlate' => 'BRA2E19',
    'make' => 'Fiat',
    'model' => 'Fiorino',
    'year' => 2023,
    'shared' => [
        [
                'id' => 'e3553bc1-5e20-4e17-b22a-a796fda0aa99',
                'role' => 'OWNER',
                'firstName' => 'Mariana',
                'lastName' => 'Costa',
                'email' => 'mariana.costa@acme.com.br'
        ]
    ],
    'customFields' => [
        'cost-center' => 'CC-1020'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vehicle.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/vehicles"

	payload := strings.NewReader("{\n  \"name\": \"Delivery van 07\",\n  \"licensePlate\": \"BRA2E19\",\n  \"make\": \"Fiat\",\n  \"model\": \"Fiorino\",\n  \"year\": 2023,\n  \"shared\": [\n    {\n      \"id\": \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\",\n      \"role\": \"OWNER\",\n      \"firstName\": \"Mariana\",\n      \"lastName\": \"Costa\",\n      \"email\": \"mariana.costa@acme.com.br\"\n    }\n  ],\n  \"customFields\": {\n    \"cost-center\": \"CC-1020\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vehicle.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/vehicles")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Delivery van 07\",\n  \"licensePlate\": \"BRA2E19\",\n  \"make\": \"Fiat\",\n  \"model\": \"Fiorino\",\n  \"year\": 2023,\n  \"shared\": [\n    {\n      \"id\": \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\",\n      \"role\": \"OWNER\",\n      \"firstName\": \"Mariana\",\n      \"lastName\": \"Costa\",\n      \"email\": \"mariana.costa@acme.com.br\"\n    }\n  ],\n  \"customFields\": {\n    \"cost-center\": \"CC-1020\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vehicle.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/vehicles")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Delivery van 07\",\n  \"licensePlate\": \"BRA2E19\",\n  \"make\": \"Fiat\",\n  \"model\": \"Fiorino\",\n  \"year\": 2023,\n  \"shared\": [\n    {\n      \"id\": \"e3553bc1-5e20-4e17-b22a-a796fda0aa99\",\n      \"role\": \"OWNER\",\n      \"firstName\": \"Mariana\",\n      \"lastName\": \"Costa\",\n      \"email\": \"mariana.costa@acme.com.br\"\n    }\n  ],\n  \"customFields\": {\n    \"cost-center\": \"CC-1020\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "6710b8e4c9e77b0012a4d6f1",
  "realmId": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
  "organizationId": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
  "name": "Delivery van 07",
  "licensePlate": "BRA2E19",
  "make": "Fiat",
  "model": "Fiorino",
  "year": 2023,
  "status": "ACTIVE",
  "external": {
    "walletId": "6710b8e4c9e77b0012a4d6f3",
    "accountId": "66f2a1c7b4d3e80012c9a0b4"
  },
  "customFields": {
    "cost-center": "CC-1020"
  },
  "createdBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
  "updatedBy": "e3553bc1-5e20-4e17-b22a-a796fda0aa99",
  "createdAt": "2026-10-17T13:45:12.000Z",
  "updatedAt": "2026-10-17T13:45:12.000Z"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "VEHICLE_ADMIN_REQUIRED",
  "origin": "VEHICLE",
  "message": "Organization admin required"
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "BAD_REQUEST",
  "origin": "VEHICLE",
  "message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
  "fields": [
    {
      "field": "name",
      "message": "Invalid input: expected string, received undefined",
      "code": "NAME_REQUIRED"
    }
  ]
}

{
  "traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
  "code": "VEHICLE_BANKING_ACCOUNT_UNAVAILABLE",
  "origin": "VEHICLE",
  "message": "No banking account is provisioned for this organization"
}

Every vehicle gets its own wallet in the organization’s account, named after the license plate, so the vehicle’s fuel and other card purchases are paid from it. The wallet is shared with the users in shared or, when you omit it, with you alone as OWNER. Every required vehicle custom field of the organization must have a value in customFields. A license plate is not unique: registering it again creates another vehicle, with a wallet of its own. Only organization admins can register vehicles. An error from the wallet service — for example when no OWNER in shared is a member of the organization — is returned with its own status, code and origin, and no vehicle is created.

Path Parameters

realmId

string<uuid>

required

ID of your realm.

Format: UUID

organizationId

string<uuid>

required

ID of the organization to register the vehicle in.

Format: UUID

Body

application/json

name

string

required

Display name of the vehicle.

Required string length: 1 - 256

Example:

"Delivery van 07"

licensePlate

string

required

License plate, in the old Brazilian format (ABC1234) or the Mercosul one (ABC1D23). Lowercase, hyphens and spaces are accepted and removed: bra-2e19 is stored as BRA2E19.

Required string length: 1 - 16

Example:

"BRA2E19"

make

string

required

Manufacturer.

Required string length: 1 - 128

Example:

"Fiat"

model

string

required

Model.

Required string length: 1 - 128

Example:

"Fiorino"

year

integer

required

Model year.

Required range: 1900 <= x <= 2100

Example:

2023

shared

object[]

Users who can use the vehicle's wallet. At least one must be an OWNER; a user who is not a member of the organization is left out. Omit it to share the wallet with you alone, as OWNER.

Minimum array length: 1

Show child attributes

customFields

object

Values of the organization's vehicle custom fields, keyed by the custom field's slug. Every required one must have a value; null, "" and [] count as no value.

Example: {"cost-center":"CC-1020"}

Show child attributes

Example:

{ "cost-center": "CC-1020" }

Response

Successful response

A vehicle of the organization's fleet.

string

required

ID of the vehicle.

Example:

"6710b8e4c9e77b0012a4d6f1"

realmId

string<uuid>

required

ID of the realm the vehicle belongs to.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

organizationId

string<uuid>

required

ID of the organization the vehicle belongs to.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

name

string

required

Display name of the vehicle.

Example:

"Delivery van 07"

licensePlate

string

required

License plate, upper-cased with no hyphen or space: the old Brazilian format (ABC1234) or the Mercosul one (ABC1D23).

Example:

"BRA2E19"

make

string

required

Manufacturer.

Example:

"Fiat"

model

string

required

Model.

Example:

"Fiorino"

year

number

required

Model year.

Example:

2023

status

enum<string>

required

ACTIVE, or ARCHIVED once the vehicle was archived. An archived vehicle's wallet is blocked.

Available options:

ACTIVE,

ARCHIVED

Example:

"ACTIVE"

external

object

required

The vehicle's dedicated wallet.

Show child attributes

customFields

object

required

Values of the organization's vehicle custom fields, keyed by the custom field's slug. Empty when none were set.

Example: {"cost-center":"CC-1020"}

Show child attributes

Example:

{ "cost-center": "CC-1020" }

createdBy

string<uuid>

ID of the user who registered the vehicle.

Example:

"e3553bc1-5e20-4e17-b22a-a796fda0aa99"

updatedBy

string<uuid>

ID of the user who last changed the vehicle.

Example:

"e3553bc1-5e20-4e17-b22a-a796fda0aa99"

createdAt

string<date-time>

When the vehicle was registered.

Example:

"2026-10-17T13:45:12.000Z"

updatedAt

string<date-time>

When the vehicle was last changed.

Example:

"2026-10-17T13:45:12.000Z"

Overview

Identity

Banking

Billing

Accounting

Registry

Platform

Notification

Rule Engine

Scheduling

Travel

Vehicles

Attachments

Create a vehicle

Path Parameters

Body

Response