# Access IDs

Access IDs include RFID cards or vehicles. When a charger identifies who is initiating a charging session, it sends us an ID tag. This ID can be from one of the following sources:

* RFID Card: A card that is scanned on the charger to authenticate the user before charging begins.
* Vehicle: The MAC ID of a vehicle that is directly plugged into the charger.

## GET /api/access-ids

Retrieve a list of all Access IDs.

### Response

The JSON response will contain a `data` field with a list of access ids, and a `pagination` field containing pagination details.

```ts
{
  data: {
    id: number;
    ocppIdTag: string;
    type: string; // RFID | Vehicle
    name: string;
    authorizationStatus: string; // Authorized | Revoked
    authorizedAt: string; // ISO 8601 format
    revokedAt: string | null; // ISO 8601 format or null. Set only if authorizationStatus is Revoked
    createdAt: string; // ISO 8601 format
    updatedAt: string; // ISO 8601 format
    // Only defined if the "type" is a vehicle:
    vehicle: {
      id: number;
      make: string | null;
      model: string | null;
      name: string;
      vin: string | null;
    } | null;
  }[];
  pagination: {
    hasNextPage: boolean;
    nextPageCursor: string | null;
  };
};
```

### Example request and response

Request:

```sh
curl "https://api.getflipturn.com/api/access-ids" -H "Authorization: Bearer {api_key}"
```

Response:

```js
{
  "data": [
    {
      "id": 123,
      "ocppIdTag": "id-tag-1",
      "type": "Vehicle",
      "name": "Vehicle 1",
      "authorizationStatus": "Authorized",
      "authorizedAt": "2024-08-02T19:13:28.897Z",
      "revokedAt": null,
      "createdAt": "2024-08-02T19:13:28.897Z",
      "updatedAt": "2024-08-08T21:29:51.795Z",
      "vehicle": {
        "id": 20,
        "make": "Tesla",
        "model": "Model 3",
        "name": "Demo Tesla",
        "vin": "demo-vin-1"
      }
    },
    {
      "id": 124,
      "ocppIdTag": "rfid-card-1",
      "type": "RFID",
      "name": "RFID Card 1",
      "authorizationStatus": "Authorized",
      "authorizedAt": "2024-08-27T15:11:37.080Z",
      "revokedAt": null,
      "createdAt": "2024-08-08T16:21:17.191Z",
      "updatedAt": "2024-08-28T19:39:35.378Z",
      "vehicle": null
    }
  ],
  "pagination": {
    "hasNextPage": true,
    "nextPageCursor": "NDMyNDc2"
  }
}
```

## GET /api/access-ids/{id}

Retrieve the details for a specific Access ID (RFID Card or Vehicle).

### Response

```ts
{
  accessId: {
    id: number;
    ocppIdTag: string;
    type: string; // RFID | Vehicle
    name: string;
    authorizationStatus: string; // Authorized | Revoked
    authorizedAt: string; // ISO 8601 format
    revokedAt: string | null; // ISO 8601 format or null. Set only if authorizationStatus is Revoked
    createdAt: string; // ISO 8601 format
    updatedAt: string; // ISO 8601 format
    vehicle: {
      id: number;
      make: string | null;
      model: string | null;
      name: string;
      vin: string | null;
    } | null;
    customer: {
      name: string
    } | null;
  }
};
```

### Example request and response

Request:

```sh
curl "https://api.getflipturn.com/api/access-ids/123" -H "Authorization: Bearer {api_key}"
```

Response:

```js
{
  "accessId": {
    "id": 123,
    "ocppIdTag": "id-tag-1",
    "type": "Vehicle",
    "name": "Vehicle 1",
    "authorizationStatus": "Authorized",
    "authorizedAt": "2024-08-02T19:13:28.897Z",
    "revokedAt": null,
    "createdAt": "2024-08-02T19:13:28.897Z",
    "updatedAt": "2024-08-08T21:29:51.795Z",
    "vehicle": {
      "id": 20,
      "make": "Tesla",
      "model": "Model 3",
      "name": "Demo Tesla",
      "vin": "demo-vin-1"
    },
    "customer": {
      "name": "Electric Fleet Transportation"
    }
  }
}
```

## POST /api/access-ids

Create a new access ID. An access ID can be of two types: RFID or Vehicle. When creating a vehicle access ID, you can either create a new vehicle by passing in the `vehicle` parameters, or associate the new access ID with an existing vehicle by passing a `vehicleId`.

A single vehicle can have multiple access IDs, which can be used to represent cases where:

1. A vehicle has multiple charging ports with different MAC IDs
2. A vehicle MAC ID has changed over time, and you wish to maintain the connection to old charging sessions

### Request Body

```ts
{
  accessId: {
    type: string; // RFID | Vehicle (required)
    name: string; // (required)
    ocppIdTag: string; // (required)
    authorizationStatus: string; // Authorized | Revoked (optional: defaults to Authorized)

    // For Vehicle type only, pass these to create a new vehicle (optional)
    vehicle?: {
      make: string; // (optional "type" param must be vehicle)
      model: string; // (optional "type" param must be vehicle)
      vin: string; // (optional "type" param must be vehicle)
    }

    // For Vehicle type only, pass a vehicleId to associate with an existing vehicle
    vehicleId?: number; // (optional)

    // Pass to associate with an existing Customer or create a new Customer. Creates a new customer
    // if no existing customer is found with the same name, case insensitive. (optional)
    customer?: {
      name: string;
    }
  }
}
```

### Response

```ts
{
  accessId: {
    id: number;
    ocppIdTag: string; // This value is normalized, and as such may not exactly match what was POSTed
    type: string; // RFID | Vehicle
    name: string;
    authorizationStatus: string; // Authorized | Revoked
    authorizedAt: string; // ISO 8601 format
    revokedAt: string | null; // ISO 8601 format or null. Set only if authorizationStatus is Revoked
    createdAt: string; // ISO 8601 format
    updatedAt: string; // ISO 8601 format
    vehicle: {
      id: number;
      make: string | null;
      model: string | null;
      name: string;
      vin: string | null;
    } | null;
    customer: {
      name: string;
    } | null;
  }
};
```

### Example request for vehicle and response

Request:

```sh
curl -X POST "https://api.getflipturn.com/api/access-ids" \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "accessId": {
    "type": "Vehicle",
    "ocppIdTag": "test-ocpp-id-tag",
    "name": "Vehicle 1",
    "vehicle": {
      "vin": "demo-vehicle-vin",
      "make": "Tesla",
      "model": "Model 3"
    },
    "customer": {
      "name": "Electric Fleet Transportation"
    }
  }
}'
```

Response:

```js
{
  "accessId": {
    "id": 123,
    "ocppIdTag": "test-ocpp-id-tag",
    "type": "Vehicle",
    "name": "Vehicle 1",
    "authorizationStatus": "Authorized",
    "authorizedAt": "2024-08-02T19:13:28.897Z",
    "revokedAt": null,
    "createdAt": "2024-08-02T19:13:28.897Z",
    "updatedAt": "2024-08-08T21:29:51.795Z",
    "vehicle": {
      "id": 20,
      "make": "Tesla",
      "model": "Model 3",
      "name": "Vehicle 1",
      "vin": "demo-vehicle-vin"
    },
    "customer": {
      "name": "Electric Fleet Transportation"
    }
  }
}
```

### Example request for RFID card and response

Request:

```sh
curl -X POST "https://api.getflipturn.com/api/access-ids" \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "accessId": {
    "type": "RFID",
    "ocppIdTag": "test-ocpp-id-tag",
    "name": "Card 1",
    "customer": {
      "name": "Electric Fleet Transportation"
    }
  }
}'
```

Response:

```js
{
  "accessId": {
    "id": 123,
    "ocppIdTag": "test-ocpp-id-tag",
    "type": "RFID",
    "name": "Card 1",
    "authorizationStatus": "Authorized",
    "authorizedAt": "2024-08-02T19:13:28.897Z",
    "revokedAt": null,
    "createdAt": "2024-08-02T19:13:28.897Z",
    "updatedAt": "2024-08-08T21:29:51.795Z",
    "vehicle": null,
    "customer": {
      "name": "Electric Fleet Transportation"
    }
  }
}
```

## PATCH /api/access-ids/{id}

Update an Access ID (RFID Card or Vehicle).

### Request Body

For optional fields, explicitly providing null will delete the value.

```ts
{
  accessId: {
    name: string;
    authorizationStatus: string; // Authorized | Revoked
    vehicle: {
      make: string;
      model: string;
      vin: string;
    },
    customer: {
      name: string;  // (creates a new customer if no existing customer is found with the same name, case insensitive)
    }
  }
}
```

### Response

```ts
{
  accessId: {
    id: number;
    ocppIdTag: string;
    type: string; // RFID | Vehicle
    name: string;
    authorizationStatus: string; // Authorized | Revoked
    authorizedAt: string; // ISO 8601 format
    revokedAt: string | null; // ISO 8601 format or null. Set only if authorizationStatus is Revoked
    createdAt: string; // ISO 8601 format
    updatedAt: string; // ISO 8601 format
    vehicle: {
      id: number;
      make: string | null;
      model: string | null;
      name: string;
      vin: string | null;
    } | null;
    customer: {
      name: string
    } | null;
  }
};
```

### Example request and response

Request:

```sh
curl -X PATCH "https://api.getflipturn.com/api/access-ids/321" \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "accessId": {
    "name": "Decommissioned Vehicle",
    "authorizationStatus": "Revoked",
    "customer": {
      "name": "Electric Fleet Transportation"
    }
  }
}'
```

Response:

```js
{
  "accessId": {
    "id": 321,
    "ocppIdTag": "test-ocpp-id-tag",
    "type": "Vehicle",
    "name": "Decommissioned Vehicle",
    "authorizationStatus": "Revoked",
    "authorizedAt": "2024-08-02T19:13:28.897Z",
    "revokedAt": "2024-08-10T15:13:28.897Z",
    "createdAt": "2024-08-02T19:13:28.897Z",
    "updatedAt": "2024-08-10T15:13:28.897Z",
    "vehicle": {
      "id": 20,
      "make": "Tesla",
      "model": "Model 3",
      "name": "Vehicle 1",
      "vin": "demo-vehicle-vin"
    },
    "customer": {
      "name": "Electric Fleet Transportation"
    }
  }
}
```

## PUT /api/access-ids/batch

Create or update up to 1000 access IDs in a single request. This endpoint is designed for syncing an entire fleet of vehicles or RFID cards with Flipturn.

The endpoint matches existing access IDs by `ocppIdTag`. If a matching access ID exists, it is updated; otherwise, a new one is created.

Vehicles are matched by `name` (case-insensitive). If no vehicle with the name exists, one is created automatically. Multiple access IDs with the same `name` are grouped onto the same vehicle.

Access IDs not included in the request are not affected, so an access ID will never be deleted from this endpoint.

### Request Body

```ts
{
  accessIds: {
    ocppIdTag: string; // (required)
    name: string; // (required)
    type: string; // RFID | Vehicle (required)
    authorizationStatus?: string; // Authorized | Revoked (optional: defaults to Authorized for new items)

    // For Vehicle type only (optional). Providing this on an RFID-type item returns an error.
    vehicle?: {
      make?: string | null;
      model?: string | null;
      vin?: string | null;
    }

    // Associate with a customer. Creates a new customer if no existing customer
    // is found with the same name (case-insensitive). (optional)
    customer?: {
      name: string;
    }
  }[] // Maximum 1000 items per request
}
```

### Edge cases

* If multiple items in a single request share the same vehicle name but provide different vehicle details (make, model, vin), the first item's details are used for the vehicle.
* If a vehicle already has telematics data, the `vin` field from the request is ignored to avoid overwriting telematics-sourced VIN data.

### Response

Each item in the `results` array corresponds to the item at the same index in the request. Items that fail are returned with `outcome: "error"` and an `error` message; other items in the batch are still processed.

```ts
{
  results: {
    ocppIdTag: string; // Normalized ocppIdTag
    outcome: string; // created | updated | error
    accessId?: {
      id: number;
      ocppIdTag: string;
      type: string; // RFID | Vehicle
      name: string;
      authorizationStatus: string; // Authorized | Revoked
      authorizedAt: string; // ISO 8601 format
      revokedAt: string | null;
      createdAt: string; // ISO 8601 format
      updatedAt: string; // ISO 8601 format
      vehicle: {
        id: number;
        make: string | null;
        model: string | null;
        name: string;
        vin: string | null;
      } | null;
      customer: {
        name: string;
      } | null;
    }; // Present when outcome is "created" or "updated"
    error?: string; // Present when outcome is "error"
  }[]
}
```

### Example request with mixed Vehicle and RFID items

Request:

```sh
curl -X PUT "https://api.getflipturn.com/api/access-ids/batch" \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
  "accessIds": [
    {
      "ocppIdTag": "mac-bus42-001",
      "name": "Bus 42",
      "type": "Vehicle",
      "vehicle": { "make": "Proterra", "model": "ZX5", "vin": "1PROTVIN0001" },
      "customer": { "name": "Metro Transit" }
    },
    {
      "ocppIdTag": "mac-bus42-002",
      "name": "Bus 42",
      "type": "Vehicle"
    },
    {
      "ocppIdTag": "rfid-badge-001",
      "name": "Driver Badge 1",
      "type": "RFID",
      "customer": { "name": "Metro Transit" }
    }
  ]
}'
```

Response:

```js
{
  "results": [
    {
      "ocppIdTag": "mac-bus42-001",
      "outcome": "created",
      "accessId": {
        "id": 500,
        "ocppIdTag": "mac-bus42-001",
        "type": "Vehicle",
        "name": "Bus 42",
        "authorizationStatus": "Authorized",
        "authorizedAt": "2025-03-17T17:00:00.000Z",
        "revokedAt": null,
        "createdAt": "2025-03-17T17:00:00.000Z",
        "updatedAt": "2025-03-17T17:00:00.000Z",
        "vehicle": {
          "id": 100,
          "make": "Proterra",
          "model": "ZX5",
          "name": "Bus 42",
          "vin": "1PROTVIN0001"
        },
        "customer": {
          "name": "Metro Transit"
        }
      }
    },
    {
      "ocppIdTag": "mac-bus42-002",
      "outcome": "created",
      "accessId": {
        "id": 501,
        "ocppIdTag": "mac-bus42-002",
        "type": "Vehicle",
        "name": "Bus 42",
        "authorizationStatus": "Authorized",
        "authorizedAt": "2025-03-17T17:00:00.000Z",
        "revokedAt": null,
        "createdAt": "2025-03-17T17:00:00.000Z",
        "updatedAt": "2025-03-17T17:00:00.000Z",
        "vehicle": {
          "id": 100,
          "make": "Proterra",
          "model": "ZX5",
          "name": "Bus 42",
          "vin": "1PROTVIN0001"
        },
        "customer": {
          "name": "Metro Transit"
        }
      }
    },
    {
      "ocppIdTag": "rfid-badge-001",
      "outcome": "created",
      "accessId": {
        "id": 502,
        "ocppIdTag": "rfid-badge-001",
        "type": "RFID",
        "name": "Driver Badge 1",
        "authorizationStatus": "Authorized",
        "authorizedAt": "2025-03-17T17:00:00.000Z",
        "revokedAt": null,
        "createdAt": "2025-03-17T17:00:00.000Z",
        "updatedAt": "2025-03-17T17:00:00.000Z",
        "vehicle": null,
        "customer": {
          "name": "Metro Transit"
        }
      }
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-docs.getflipturn.com/access-ids.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.