# Create Cost Centres Through the Fleetr API

Create a cost centre from another business system while keeping Fleetr as the source of its name, code and vehicle assignments.

Last updated: <time datetime="2026-10-20">20 October 2026</time>.

## Prepare Cost Centre Creation

Use an account integration token with permission to manage cost centres in the selected account. This normally requires an unrestricted account administrator. A role held in another account does not grant management access here. The account must have full access under Fleetr's subscription rules; read-only or blocked access cannot create cost centres. Account API tokens are subject to their role and plan restrictions.

Send an explicit numeric **X-Account-ID** header. The token must belong to that account. This endpoint does not fall back to a default account. Human users must have a complete phone profile; machine integration users do not need a personal phone number.

Generate a UUID for **Idempotency-Key** and store it with the intended request before sending it. Reuse that key when retrying the same operation after a timeout or lost response. This prevents creating a second cost centre when Fleetr accepted the first request but the caller did not receive the result.

See [API integration](/docs/api-integration) for token setup and the [interactive API reference](https://fleetr.co.ke/api/docs) for the complete request schema.

## Send a Cost Centre Request

Send a JSON body to `POST /api/cost-centers`:

```http
POST /api/cost-centers HTTP/1.1
Host: fleetr.co.ke
Authorization: Bearer YOUR_ACCOUNT_API_TOKEN
Accept: application/json
Content-Type: application/json
X-Account-ID: 123
Idempotency-Key: 35e199da-a873-4876-aa79-2349f3d7e76a

{"name":"North Rift","code":"NR-01"}
```

The account ID, key and cost-centre details above are examples. Use your own account and generate a new UUID for each new creation operation. Keep the real token private.

| Field | Requirement |
|---|---|
| `name` | Required text, up to 100 characters after whitespace normalization |
| `code` | Optional text, up to 50 characters after normalization; omitted, blank or `null` means no code |
| `account_id` | Optional account ID that must match **X-Account-ID** |

Fleetr trims surrounding whitespace and collapses repeated whitespace in names and codes. Names and non-empty codes must be unique within the account, ignoring case, including those belonging to archived cost centres. Other JSON fields and query parameters are rejected.

## Read the Created Cost Centre

The first successful request returns **201 Created**:

```json
{
  "data": {
    "cost_center": {
      "id": 456,
      "account_id": 123,
      "name": "North Rift",
      "code": "NR-01"
    }
  }
}
```

Store the returned ID with the Fleetr account ID in your integration. Use this ID when assigning the cost centre to a vehicle through the supported vehicle API. Match records by their IDs rather than by name or code.

For callers allowed to create vehicles, `GET /api/accounts` includes each accessible account's active, assignable `cost_centers`. A vehicle response also includes its current `cost_center` reference. Catalogue availability can differ from vehicle read access.

## Retry Cost Centre Creation Safely

Retry with the **same UUID**, selected account and normalized name/code. Fleetr returns **200 OK** with the original creation response and creates no additional record. Omitted and `null` codes are equivalent; insignificant whitespace is normalized. Letter-case changes count as a different request even though duplicate-name checks ignore case.

The original response is retained even if the cost centre is renamed later. Use the active catalogue or vehicle reference to refresh its current details. Current authentication, account permissions and subscription access are still required for a replay.

A key already used with different name/code values returns **409 Conflict**. Restore the original request for a retry, or start a deliberate new operation with a new UUID. Keys are scoped to the selected Fleetr account.

A new key with an existing name or code returns **422 Unprocessable Content**. Fleetr does not adopt an existing cost centre based on similar text. Resolve the duplicate in Fleetr or choose a distinct name/code before trying again. Validation failures do not claim the key.

## Resolve Cost Centre API Errors

| Status | Check |
|---|---|
| **401** | Supply a valid bearer token |
| **402** | Restore full subscription access before creating or retrying |
| **403** | Check selected-account membership, the token's management role, cost-centre restrictions and any required phone profile |
| **409** | The UUID belongs to a different normalized request; reuse the original request or choose a new UUID for a new operation |
| **422** | Correct the JSON fields, required account/key headers, matching account ID, lengths or duplicate name/code |
| **429** | Slow down and retry later with the same key and payload; this endpoint allows 30 requests per minute |

If a connection fails before a response arrives, keep the same key and payload for the retry. Manage later edits, archival and restoration through Fleetr. Existing vehicle or member assignments must be moved before archiving a cost centre.