> ## Documentation Index
> Fetch the complete documentation index at: https://dynamo-csms.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Commissioning API — Validate and Activate Chargers

> Run and monitor the charge point commissioning workflow. Track check status, apply templates, retrieve diagnostics, and report issues.

The commissioning workflow validates that a newly installed charge point is correctly configured and communicating with Dynamo CSMS before it goes live for EV drivers. All commissioning endpoints are authenticated with an installer JWT (obtained from `POST /api/v1/installer/login`) and scoped to a specific `charge_point_id`.

A typical commissioning flow:

1. **Start** the session — triggers connectivity and configuration checks
2. **Poll status** — monitor test progress
3. **Apply a template** if standard checks fail
4. **Review logs and diagnostics** to diagnose failures
5. **Report issues** for hardware defects or site problems
6. **Commission** when all checks pass (see [Charge Points](/api/charge-points))

***

## Start commissioning

`POST /api/v1/installer/commissioning/{charge_point_id}/start`

Kicks off a commissioning session for the charge point. The system runs a sequence of automated checks: OCPP connectivity, heartbeat, configuration validation, and a test transaction.

<ParamField path="charge_point_id" type="string" required>
  The unique identifier of the charge point to commission.
</ParamField>

<ParamField body="template_id" type="string">
  Optional commissioning template to apply before running checks. If omitted, the default template for the charge point model is used.
</ParamField>

<ParamField body="skip_test_transaction" type="boolean">
  Set to `true` to skip the test transaction step. Useful on sites where a vehicle is not available during commissioning. Defaults to `false`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/start \
    -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "template_id": "tpl_standard_ac_22kw",
      "skip_test_transaction": false
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/start",
      headers={"Authorization": "Bearer INSTALLER_ACCESS_TOKEN"},
      json={
          "template_id": "tpl_standard_ac_22kw",
          "skip_test_transaction": False,
      },
  )
  print(response.json())
  ```
</CodeGroup>

**Response `202 Accepted`**

```json theme={null}
{
  "charge_point_id": "CP-SITE42-001",
  "session_id": "comm_9f2c4a7b",
  "status": "running",
  "started_at": "2024-03-10T14:30:00Z",
  "estimated_duration_seconds": 120,
  "steps": [
    {"name": "connectivity", "status": "pending"},
    {"name": "heartbeat", "status": "pending"},
    {"name": "configuration", "status": "pending"},
    {"name": "test_transaction", "status": "pending"}
  ]
}
```

<ResponseField name="session_id" type="string">
  Unique identifier for this commissioning session.
</ResponseField>

<ResponseField name="status" type="string">
  Initial status is `running`. Poll the status endpoint to track progress.
</ResponseField>

<ResponseField name="steps" type="array">
  Ordered list of commissioning steps with their individual statuses.
</ResponseField>

***

## Get commissioning status

`GET /api/v1/installer/commissioning/{charge_point_id}/status`

Returns the current state of the active (or most recent) commissioning session for the charge point.

<ParamField path="charge_point_id" type="string" required>
  The charge point's unique identifier.
</ParamField>

```bash theme={null}
curl https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/status \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"
```

**Response `200 OK`**

```json theme={null}
{
  "charge_point_id": "CP-SITE42-001",
  "session_id": "comm_9f2c4a7b",
  "status": "completed",
  "result": "passed",
  "started_at": "2024-03-10T14:30:00Z",
  "completed_at": "2024-03-10T14:32:15Z",
  "steps": [
    {
      "name": "connectivity",
      "status": "passed",
      "duration_ms": 342,
      "detail": "WebSocket connected successfully"
    },
    {
      "name": "heartbeat",
      "status": "passed",
      "duration_ms": 1050,
      "detail": "Heartbeat received within 2s"
    },
    {
      "name": "configuration",
      "status": "passed",
      "duration_ms": 8200,
      "detail": "All 12 configuration keys applied"
    },
    {
      "name": "test_transaction",
      "status": "passed",
      "duration_ms": 25600,
      "detail": "Test transaction completed, 0.02 kWh delivered"
    }
  ]
}
```

<ResponseField name="status" type="string">
  One of: `running`, `paused`, `completed`, `stopped`, `failed`.
</ResponseField>

<ResponseField name="result" type="string | null">
  `passed` or `failed` once the session is complete. `null` while still running.
</ResponseField>

<ResponseField name="steps[].status" type="string">
  Individual step result: `pending`, `running`, `passed`, `failed`, `skipped`.
</ResponseField>

***

## Stop commissioning

`POST /api/v1/installer/commissioning/{charge_point_id}/stop`

Stops the active commissioning session. Use this if you need to abort due to hardware or site issues.

```bash theme={null}
curl -X POST https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/stop \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"
```

**Response `200 OK`**

```json theme={null}
{
  "charge_point_id": "CP-SITE42-001",
  "session_id": "comm_9f2c4a7b",
  "status": "stopped",
  "stopped_at": "2024-03-10T14:31:00Z"
}
```

***

## Pause commissioning

`POST /api/v1/installer/commissioning/{charge_point_id}/pause`

Pauses the running session at the current step. Useful when the charge point needs brief physical attention during commissioning.

```bash theme={null}
curl -X POST https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/pause \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"
```

**Response `200 OK`**

```json theme={null}
{
  "charge_point_id": "CP-SITE42-001",
  "session_id": "comm_9f2c4a7b",
  "status": "paused",
  "paused_at": "2024-03-10T14:31:00Z",
  "paused_at_step": "configuration"
}
```

***

## Resume commissioning

`POST /api/v1/installer/commissioning/{charge_point_id}/resume`

Resumes a paused commissioning session from where it left off.

```bash theme={null}
curl -X POST https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/resume \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"
```

**Response `200 OK`**

```json theme={null}
{
  "charge_point_id": "CP-SITE42-001",
  "session_id": "comm_9f2c4a7b",
  "status": "running",
  "resumed_at": "2024-03-10T14:35:00Z",
  "resuming_at_step": "configuration"
}
```

***

## Restart commissioning

`POST /api/v1/installer/commissioning/{charge_point_id}/restart`

Starts a fresh commissioning session from the beginning, discarding the current session's results.

<ParamField body="template_id" type="string">
  Optionally switch to a different commissioning template for the new session.
</ParamField>

```bash theme={null}
curl -X POST https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/restart \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Response `202 Accepted`** — same schema as the start response.

***

## Get commissioning logs

`GET /api/v1/installer/commissioning/{charge_point_id}/logs`

Returns detailed event logs for the current or most recent commissioning session. Useful for debugging failures.

<ParamField path="charge_point_id" type="string" required>
  The charge point's unique identifier.
</ParamField>

<ParamField query="session_id" type="string">
  Retrieve logs for a specific historical session. Omit to get the most recent session's logs.
</ParamField>

<ParamField query="level" type="string">
  Filter by log level: `debug`, `info`, `warn`, `error`. Defaults to all levels.
</ParamField>

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/logs?level=error" \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"
```

**Response `200 OK`**

```json theme={null}
{
  "charge_point_id": "CP-SITE42-001",
  "session_id": "comm_9f2c4a7b",
  "logs": [
    {
      "timestamp": "2024-03-10T14:30:01Z",
      "level": "info",
      "step": "connectivity",
      "message": "Attempting WebSocket connection to charge point"
    },
    {
      "timestamp": "2024-03-10T14:30:01.342Z",
      "level": "info",
      "step": "connectivity",
      "message": "WebSocket connected successfully"
    },
    {
      "timestamp": "2024-03-10T14:30:45Z",
      "level": "warn",
      "step": "configuration",
      "message": "Key 'ReserveConnectorZeroSupported' not supported by firmware — skipped"
    }
  ],
  "total": 47
}
```

***

## Report an issue

`POST /api/v1/installer/commissioning/{charge_point_id}/report-issue`

Submits an issue report for a commissioning problem, flagging it for review by the Dynamo CSMS support team or the CPO.

<ParamField path="charge_point_id" type="string" required>
  The charge point's unique identifier.
</ParamField>

<ParamField body="category" type="string" required>
  Issue category. One of: `hardware_defect`, `network_problem`, `configuration_error`, `site_issue`, `other`.
</ParamField>

<ParamField body="description" type="string" required>
  Detailed description of the issue. Minimum 20 characters.
</ParamField>

<ParamField body="severity" type="string" required>
  One of: `low`, `medium`, `high`, `critical`.
</ParamField>

<ParamField body="step" type="string">
  The commissioning step where the issue occurred (e.g. `"configuration"`, `"test_transaction"`).
</ParamField>

<ParamField body="photo_urls" type="string[]">
  URLs of photos uploaded to document the issue (hardware damage, wiring, etc.).
</ParamField>

```bash theme={null}
curl -X POST https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/report-issue \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "network_problem",
    "description": "Charge point connects briefly then drops WebSocket connection after ~5 seconds. Tested on both 4G and site WiFi. Issue persists across factory resets.",
    "severity": "high",
    "step": "connectivity",
    "photo_urls": [
      "https://storage.example.com/photos/cp_site42_001_lcd.jpg"
    ]
  }'
```

**Response `201 Created`**

```json theme={null}
{
  "issue_id": "iss_4c8f2a1b",
  "charge_point_id": "CP-SITE42-001",
  "category": "network_problem",
  "severity": "high",
  "status": "open",
  "created_at": "2024-03-10T15:00:00Z",
  "reference_number": "DYN-2024-00847"
}
```

***

## List issues

`GET /api/v1/installer/commissioning/{charge_point_id}/issues`

Returns all issue reports filed for this charge point.

```bash theme={null}
curl https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/issues \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"
```

**Response `200 OK`**

```json theme={null}
{
  "issues": [
    {
      "issue_id": "iss_4c8f2a1b",
      "category": "network_problem",
      "severity": "high",
      "status": "open",
      "created_at": "2024-03-10T15:00:00Z",
      "reference_number": "DYN-2024-00847"
    }
  ],
  "total": 1
}
```

***

## List commissioning templates

`GET /api/v1/installer/commissioning/templates`

Returns all available commissioning templates. Templates pre-configure OCPP parameters and commissioning steps for specific hardware models or deployment scenarios.

```bash theme={null}
curl https://api.dynamo-csms.com/api/v1/installer/commissioning/templates \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"
```

**Response `200 OK`**

```json theme={null}
{
  "templates": [
    {
      "template_id": "tpl_standard_ac_22kw",
      "name": "Standard AC 22kW",
      "description": "Default commissioning for Type 2 AC chargers up to 22kW.",
      "compatible_models": ["ABB Terra AC W22-G5", "Schneider EVlink Pro AC"],
      "steps": ["connectivity", "heartbeat", "configuration", "test_transaction"],
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "template_id": "tpl_dc_rapid_50kw",
      "name": "DC Rapid 50kW",
      "description": "Commissioning template for DC rapid chargers with CHAdeMO and CCS connectors.",
      "compatible_models": ["ABB Terra 54 CJG", "Tritium PKM75"],
      "steps": ["connectivity", "heartbeat", "configuration", "connector_test", "test_transaction"],
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 2
}
```

***

## Apply template

`POST /api/v1/installer/commissioning/{charge_point_id}/apply-template`

Applies a commissioning template to a charge point mid-session, pushing OCPP configuration keys defined in the template to the hardware.

<ParamField path="charge_point_id" type="string" required>
  The charge point's unique identifier.
</ParamField>

<ParamField body="template_id" type="string" required>
  The ID of the template to apply.
</ParamField>

```bash theme={null}
curl -X POST https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/apply-template \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "tpl_standard_ac_22kw"}'
```

**Response `200 OK`**

```json theme={null}
{
  "charge_point_id": "CP-SITE42-001",
  "template_id": "tpl_standard_ac_22kw",
  "applied_keys": 12,
  "rejected_keys": ["ReserveConnectorZeroSupported"],
  "applied_at": "2024-03-10T14:32:00Z"
}
```

<ResponseField name="applied_keys" type="integer">
  Number of configuration keys successfully applied.
</ResponseField>

<ResponseField name="rejected_keys" type="string[]">
  Keys that were not applied — usually because the firmware does not support them.
</ResponseField>

***

## Get diagnostics

`GET /api/v1/installer/commissioning/{charge_point_id}/diagnostics`

Returns hardware and firmware diagnostic information reported by the charge point during commissioning. Useful for support escalations and firmware compatibility checks.

```bash theme={null}
curl https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/diagnostics \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"
```

**Response `200 OK`**

```json theme={null}
{
  "charge_point_id": "CP-SITE42-001",
  "collected_at": "2024-03-10T14:30:05Z",
  "firmware": {
    "version": "3.8.2",
    "vendor": "ABB",
    "last_updated": "2023-11-01T00:00:00Z"
  },
  "ocpp": {
    "version": "1.6",
    "supported_features": [
      "Core", "FirmwareManagement", "LocalAuthListManagement",
      "Reservation", "SmartCharging", "RemoteTrigger"
    ]
  },
  "network": {
    "interface": "ethernet",
    "ip_address": "192.168.1.101",
    "signal_strength": null,
    "dns_resolution_ok": true,
    "ntp_synced": true
  },
  "hardware": {
    "connectors": 2,
    "meter_type": "MID certified",
    "rcd_present": true
  },
  "configuration_readonly_keys": [
    "ChargePointVendor",
    "ChargePointModel",
    "ChargePointSerialNumber"
  ]
}
```

***

## Error responses

| Status | Code                      | Meaning                                                         |
| ------ | ------------------------- | --------------------------------------------------------------- |
| `400`  | `validation_error`        | Missing or invalid request field                                |
| `401`  | `unauthorized`            | Missing or expired installer token                              |
| `404`  | `not_found`               | Charge point or template not found                              |
| `409`  | `session_already_running` | A commissioning session is already active for this charge point |
| `409`  | `not_connected`           | Charge point is not currently connected via OCPP                |
| `422`  | `already_commissioned`    | Charge point has already been commissioned                      |