SimItNow API reference

Authentication

Every request to the SimItNow API must include your API key in the SIMITNOW-API-KEY header. No request body is needed for authentication; it is checked on every call automatically.

Example

curl -X GET https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Probe a CSMS

Attempt one real WebSocket handshake against the URL a station would use, then close. Nothing is created, and no BootNotification is sent, so probing leaves no session, registration or log entry on your CSMS. Always returns HTTP 200 when the probe ran: the verdict is in the body. Rate limited to 20 probes per minute per API key; the handshake times out after 8 seconds.

Request

Response

The response never contains the CSMS's own response body, only the status code and SimItNow's classification of it.

Response codes

Diagnosis codes

Example

curl -X POST https://api.simitnow.com/v1/cs/probe   -H "SIMITNOW-API-KEY: $api_key"   -H "Content-Type: application/json"   -d '{"csmsUrl":"wss://csms.example.com/ocpp","id":"CP-001","protocol":"ocpp1.6"}'

{"ok": false, "code": "path_not_found",
 "cause": "The server does not recognise this path",
 "action": "Check the path in the URL - did you replace the example value?",
 "stages": {"dns": "ok", "tcp_tls": "ok", "ocpp_ws": "fail"},
 "statusCode": 404, "url": "wss://csms.example.com/ocpp/CP-001"}

Create Charging Station

Create and connect a new simulated charging station. The station sends a BootNotification to the CSMS at the provided URL as soon as it has connected. Returns HTTP 201 Created on success.

Add ?probe=1 to check the CSMS is reachable before the station is created. On failure nothing is created and the call returns HTTP 422 with the same diagnosis body as the probe endpoint. It is opt-in on purpose: the probe can take up to 8 seconds, so making it unconditional would turn a bulk create of several hundred stations into hours. Leave the flag off for batch work and pass it when you are wiring up a station by hand.

Request

Response

HTTP 201 Created
{"id": "CP-001"}

The 201 comes back as soon as the station is created, before it has connected to your CSMS. Until the connection is up, calls that name the station answer HTTP 409 with connectionStatus set to connecting and a Retry-After header in seconds. Wait that long and call again, or poll Get Charging Station Info until it answers 200. You can delete the station at any time. If your CSMS cannot be reached, the station keeps retrying and the calls keep answering 409 until you delete it. A station that is paused until the daily message allowance resets or is raised answers 409 too, with a quotaPause object and no Retry-After header.

Errors

• 409 {"error": "Simulator CP-001 exists"}: station with this ID already active
• 400 {"error": "Unsupported protocol: xyz"}: unrecognised protocol value
• 400 {"error": "basicAuth and clientCert are mutually exclusive"}: choose either SP-1 Basic Auth or SP-3 client certificate, not both
• 400 {"error": "clientCert requires wss:// (TLS transport)"}: SP-3 requires a TLS WebSocket URL
• 400 {"error": "authorizeLocalStart must be true or false"}: the field is present but is not a JSON boolean ("false" and 0 are refused too). Leave it out, or send null, to get the default
• 400 {"error": "iccid must be a string of 1 to 20 printable ASCII characters"}: iccid or imsi is not a string, is blank, is longer than 20 characters or contains anything but printable ASCII (the message names the field)
• 429 {"error": "Charging station limit reached: ..."}: a Free account has a safety limit on how many charging stations it can hold. The stations you already have keep running, nothing is stopped or deleted, but you cannot create new ones until you are under the limit. Delete a station, or email us if you need more
• 429 {"error": "quota_exceeded", ...}: today's OCPP message allowance is used up. It resets at 00:00 UTC, and the body carries message_limit and message_count

Example

curl -X PUT https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"ws://your-csms:9000","protocol":"ocpp1.6"}'

Connection Security

The security object controls how the simulated charging station authenticates when it opens the outbound WebSocket to your CSMS. API authentication is separate and always uses the SIMITNOW-API-KEY request header.

security.basicAuth and security.clientCert are mutually exclusive. Client certificates require wss://; otherwise the API returns clientCert requires wss:// (TLS transport).

Security Whitepaper Messages

For CSMS testing, SimItNow advertises the OCPP 1.6 Security feature profile and responds to Security Whitepaper messages with deterministic simulator behavior. It accepts or records GetLog, InstallCertificate, CertificateSigned, DeleteCertificate, GetInstalledCertificateIds, and ExtendedTriggerMessage; it can also send SignCertificate, SecurityEventNotification, and LogStatusNotification when triggered. Certificate handling is in-memory and intended for CSMS workflow validation, not real charge point trust-chain enforcement.

SP-0 Plain WebSocket

curl -X PUT https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"ws://your-csms:9000","protocol":"ocpp1.6"}'

SP-1 Basic Auth

curl -X PUT https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"ws://your-csms:9000","protocol":"ocpp1.6","security":{"basicAuth":{"username":"shared-user","password":"secret"}}}'

SP-2 TLS / WSS

curl -X PUT https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"wss://your-csms:9443","protocol":"ocpp1.6","security":{"skipServerCertVerify":true}}'

SP-3 Client Certificate

curl -X PUT https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"wss://your-csms:9443","protocol":"ocpp1.6","security":{"clientCert":{"certificate":"-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
","privateKey":"-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
"}}}'

Get Charging Station Info

Retrieve the current configuration and connector state of a running station. No request body.

Response

HTTP 200 OK
{"config": {...}, "connector": {...}, "network": {"connected": true, "queuedMessages": 0},
 "iccid": "8949000000000000001", "imsi": "001010123456789", "authorizeLocalStart": true}

The config object contains the creation parameters; connector contains per-connector state (status, error code, active transaction). network.connected is false while the station is disconnected, and network.queuedMessages counts the transaction messages it is holding until the connection returns. iccid and imsi are the SIM details the station reports in BootNotification, or null when you did not set them at creation. authorizeLocalStart is what the station does now: true when a local start sends Authorize first, false when it does not (the value you created it with, unless your CSMS changed AuthCtrlr.Enabled since), and null on OCPP 1.6.

Errors

• 404 {"error": "Simulator CP-001 not found"}
• 409 {"error": "Simulator CP-001 is still connecting to the CSMS. ...", "connectionStatus": "connecting"}: the station was created but has not connected to your CSMS yet. Wait for the Retry-After header (seconds) and call again

Example

curl -X GET https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Delete Charging Station

Stop and remove a simulated charging station. No request body.

Response

HTTP 200 OK
{"id": "CP-001"}

Errors

• 404 {"error": "Simulator CP-001 not found"}

Example

curl -X DELETE https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Transaction Start

Start a charging transaction on a connector. The connector must be in preparing state, which requires an EV to already be connected (via ev/{ev_id}/connection). Returns HTTP 400 if the connector is not ready.

On OCPP 2.0.1 and 2.1 the station first sends Authorize with the token and starts the transaction only if your CSMS answers Accepted. Those versions do not need an EV to be plugged in, unless your CSMS sets a TxStartPoint that has no Authorized. Plugging an EV in already starts a transaction by itself there, so do not call transactions after ev/{ev_id}/connection on a 2.x station (you would get a 409, see below). To skip Authorize, create the station with authorizeLocalStart set to false, or set AuthCtrlr.Enabled to false with SetVariables. A station that is offline skips it too.

An EVSE takes one transaction at a time. On OCPP 2.0.1 and 2.1 a second start is refused while the EVSE has a running transaction or another start is waiting, and the first transaction is left alone. A connector that is Faulted or Unavailable cannot start a transaction either, and a refused start does not change its status.

Your CSMS chooses the moment a transaction starts with TxCtrlr.TxStartPoint. The station's own value is Authorized: the transaction starts when the token is accepted. With EVConnected,Authorized, plugging an EV in starts the transaction before anyone is authorized, and the station then sends Authorize with the EV's idTag by itself. If that Authorize is refused or gets no answer, this call gives the waiting transaction its token instead of opening a second one, and the answer carries that transaction's transactionId. While the station's own Authorize is still pending, or once it was accepted, this call answers 409. A transaction that started before any EV was plugged in ends with trigger reason EVConnectTimeout when no cable comes within TxCtrlr.EVConnectionTimeOut seconds (30 by default), so plug the EV in within that time or raise the value.

Request

Response

HTTP 200 OK
{"transactionId": 1}

Save transactionId; it is needed to stop the transaction.

On OCPP 1.6 a station that is currently disconnected returns a negative transactionId. The real one is assigned by your CSMS when the queued StartTransaction is delivered on reconnect; the negative value is a local placeholder and stops the transaction just as well in the meantime.

Errors

• 400 {"error": "Connector not in preparing state"}: EV not yet connected or connector not ready
• 400 {"error": "Authorize was not accepted: Blocked", "authorizationStatus": "Blocked"}: OCPP 2.0.1 and 2.1 only. Your CSMS answered Authorize with a status other than Accepted, so no transaction started. If it accepted the token only for other EVSEs, the body also lists them in allowedEvseIds
• 404 {"error": "Simulator CP-001 not found"}
• 409 {"error": "Simulator CP-001 is still connecting to the CSMS. ...", "connectionStatus": "connecting"}: the station was created but has not connected to your CSMS yet. Wait for the Retry-After header (seconds) and call again
• 409 {"error": "A start is already in progress on this EVSE"}: OCPP 2.0.1 and 2.1 only. An earlier start is still waiting for the Authorize answer
• 409 {"error": "TxStartPoint is EVConnected: no EV is plugged in. ..."}: OCPP 2.0.1 and 2.1 only. TxStartPoint has no Authorized and no EV is plugged in, or it is EnergyTransfer and the plugged-in EV takes no energy. Nothing was sent. Plug an EV in first, or have your CSMS add Authorized to TxStartPoint
• 409 {"error": "A transaction is already running on EVSE 1 (transactionId ...): stop it before starting another", "runningTransactionId": "..."}: OCPP 2.0.1 and 2.1 only. Stop the running transaction first, or start on another EVSE
• 409 {"error": "Connector 1 of EVSE 1 is Faulted: ...", "connectorStatus": "Faulted"}: OCPP 2.0.1 and 2.1 only. A Faulted or Unavailable connector cannot start a transaction. Clear the fault, or have your CSMS make the connector available, then try again
• 502 {"error": "The CSMS did not answer Authorize (...). Fix the CSMS, or delete this station and create it again with authorizeLocalStart set to false. Your CSMS can also send SetVariables with AuthCtrlr.Enabled=false."}: OCPP 2.0.1 and 2.1 only. The call waits up to 10 seconds for the answer before it fails, so give your HTTP client a longer timeout
• 503 {"error": "Simulator CP-001 is offline and its message queue is full"}: the transaction was deliberately not started, since the station could not keep the message for delivery

Example

curl -X POST https://api.simitnow.com/v2/cs/CP-001/transactions   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"connectorId":1}'

Transaction Stop

Stop an active charging transaction.

The transaction ID is passed in the URL path.

On OCPP 2.0.1 and 2.1 your CSMS chooses with TxCtrlr.TxStopPoint what this call ends. The station's own value is Authorized,EVConnected, and with it this call ends the transaction with one Ended event. If your CSMS sets a list with neither Authorized nor PowerPathClosed, the call ends only the authorization, unless EnergyTransfer is in the list. With EVConnected alone the station stops the energy, sends an Updated event with trigger reason StopAuthorized and the token, and answers 200. The transaction ends when the EV is unplugged, or when you call this again, because a transaction with no token left has nothing else to end. With EnergyTransfer the station sends the same Updated event and then an Ended event with trigger reason ChargingStateChanged.

Response

HTTP 200 OK
{}

Errors

• 400 {"error": "Transaction not found or already stopped"}
• 404 {"error": "Simulator CP-001 not found"}
• 409 {"error": "Simulator CP-001 is still connecting to the CSMS. ...", "connectionStatus": "connecting"}: the station was created but has not connected to your CSMS yet. Wait for the Retry-After header (seconds) and call again

Example

curl -X DELETE https://api.simitnow.com/v2/cs/CP-001/transactions/1   -H "SIMITNOW-API-KEY: <your-key>"

Error Set

Put a connector into a faulted state by setting an OCPP error code.

A transaction running on that connector ends with the fault. On OCPP 2.0.1 and 2.1 the station sends TransactionEvent Ended with trigger reason AbnormalCondition, and the connector stays Faulted until you reset the fault. The stopped reason is GroundFault for GroundFailure, OvercurrentFault for OverCurrentFailure, PowerQuality for OverVoltage and UnderVoltage, and Other for any other code.

Request

Response

HTTP 200 OK
{}

Errors

• 400 {"error": "Invalid errorCode: xyz"}
• 404 {"error": "Simulator CP-001 not found"}
• 409 {"error": "Simulator CP-001 is still connecting to the CSMS. ...", "connectionStatus": "connecting"}: the station was created but has not connected to your CSMS yet. Wait for the Retry-After header (seconds) and call again

Example

curl -X POST https://api.simitnow.com/v2/cs/CP-001/fault   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"connectorId":1,"errorCode":"GroundFailure"}'

Error Reset

Clear a faulted connector, returning it to normal operation.

The connector ID is passed in the URL path.

On OCPP 2.0.1 and 2.1 the connector then reports Occupied if an EV is still plugged into it, and Available if not. If a change to Inoperative was waiting for a transaction, the connector becomes Unavailable instead. Available becomes Reserved while the EVSE has a reservation. On OCPP 1.6 the connector reports Available, and then Preparing again if an EV is still plugged in.

Response

HTTP 200 OK
{}

Errors

• 404 {"error": "Simulator CP-001 not found"}
• 409 {"error": "Simulator CP-001 is still connecting to the CSMS. ...", "connectionStatus": "connecting"}: the station was created but has not connected to your CSMS yet. Wait for the Retry-After header (seconds) and call again
• 400 {"error": "Connector not in a faulted state"}

Example

curl -X DELETE https://api.simitnow.com/v2/cs/CP-001/fault/1   -H "SIMITNOW-API-KEY: <your-key>"

Security Event

Make the station send an OCPP 1.6 SecurityEventNotification. Security events are reported by the station itself, so there is no CSMS command that triggers one; this endpoint is how you exercise your CSMS's handling of them.

Request

Response

HTTP 200 OK
{}

Errors

• 400 {"error": "type is required and must be a non-empty string"}
• 404 {"error": "Simulator CP-001 not found"}
• 409 {"error": "Simulator CP-001 is still connecting to the CSMS. ...", "connectionStatus": "connecting"}: the station was created but has not connected to your CSMS yet. Wait for the Retry-After header (seconds) and call again

Example

curl -X POST https://api.simitnow.com/v2/cs/CP-001/security-event   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"type":"TamperDetectionActivated","techInfo":"enclosure sensor 3"}'

Network Disconnect

Drop the WebSocket connection immediately. With a duration the station reconnects when it has passed; without one it stays offline until you call network/connect.

Optional body: {"duration": 30} (seconds to stay disconnected before the station reconnects on its own; 0 = reconnect immediately).

The station keeps running while disconnected: meters advance, connector status changes, and a transaction can still be started for an id tag held in the local authorization list. Transaction messages produced during the outage (StartTransaction, MeterValues, StopTransaction, or TransactionEvent on OCPP 2.0.1) are queued and delivered in order once the connection returns; OCPP 2.0.1 events are marked offline: true. Heartbeats and status notifications are not queued; the station reports its current status once it is back. A transaction started offline on OCPP 1.6 reports a negative placeholder transaction id until the CSMS assigns the real one during replay.

RemoteStartTransaction cannot reach a disconnected station: it travels from the CSMS to the station, so there is no connection for it to arrive on.

Response

HTTP 200 OK
{}

Errors

• 404 {"error": "Simulator CP-001 not found"}
• 409 {"error": "Simulator CP-001 is still connecting to the CSMS. ...", "connectionStatus": "connecting"}: the station was created but has not connected to your CSMS yet. Wait for the Retry-After header (seconds) and call again
• 409 {"error": "Simulator CP-001 is already disconnected"}

Example

curl -X POST https://api.simitnow.com/v2/cs/CP-001/network/disconnect   -H "SIMITNOW-API-KEY: <your-key>"

Network Connect

Trigger an immediate reconnect attempt. No request body.

Response

HTTP 200 OK
{}

Errors

• 404 {"error": "Simulator CP-001 not found"}
• 409 {"error": "Simulator CP-001 is still connecting to the CSMS. ...", "connectionStatus": "connecting"}: the station was created but has not connected to your CSMS yet. Wait for the Retry-After header (seconds) and call again
• 409 {"error": "Simulator CP-001 is already connected"}

Example

curl -X POST https://api.simitnow.com/v2/cs/CP-001/network/connect   -H "SIMITNOW-API-KEY: <your-key>"

Power Loss

Simulate a power cut: every active transaction is stopped with reason PowerLoss, then the station goes offline indefinitely. No request body.

The sessions are stopped before the station goes offline, so your CSMS receives the StopTransaction messages straight away and sees how each session ended. Use POST /v2/cs/{cb_id}/network/connect to bring the station back.

Response

HTTP 200 OK
{}

Errors

• 404 {"error": "Simulator CP-001 not found"}
• 409 {"error": "Simulator CP-001 is still connecting to the CSMS. ...", "connectionStatus": "connecting"}: the station was created but has not connected to your CSMS yet. Wait for the Retry-After header (seconds) and call again
• 409 {"error": "Simulator CP-001 is already disconnected"}

Example

curl -X POST https://api.simitnow.com/v2/cs/CP-001/network/power-loss   -H "SIMITNOW-API-KEY: <your-key>"

Create Electric Vehicle

Create a new virtual electric vehicle. Returns HTTP 201 Created on success.

Request

Response

HTTP 201 Created
{"id": "EV-01"}

Errors

• 409 {"error": "EV-01 exists"}

Example

curl -X PUT https://api.simitnow.com/v2/ev/EV-01   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"batteryCapacity":60}'

Get Electric Vehicle Info

Retrieve the current state of a virtual EV, including SOC and connection status. No request body.

Response

HTTP 200 OK
{
  "id": "EV-01",
  "soc": 42.5,
  "capacityWh": 60000,
  "connectedCbId": "CP-001",
  "connectedConnectorId": 1,
  "autoDischarge": true,
  "idTag": "ABC123",
  "maxAcPowerKw": 11,
  "maxDcPowerKw": 90
}

connectedCbId and connectedConnectorId are null when the EV is not connected.

Errors

• 404 {"error": "No active EV found with ev_id: EV-01"}

Example

curl -X GET https://api.simitnow.com/v2/ev/EV-01   -H "SIMITNOW-API-KEY: <your-key>"

Delete Electric Vehicle

Remove a virtual EV. If the EV is connected to a station, it is automatically disconnected first. No request body.

Response

HTTP 200 OK
{"id": "EV-01"}

Errors

• 404 {"error": "EV-01 not found"}

Example

curl -X DELETE https://api.simitnow.com/v2/ev/EV-01   -H "SIMITNOW-API-KEY: <your-key>"

Connect Electric Vehicle

Plug the EV into a connector on a charging station. The connector transitions to preparing state asynchronously. Poll GET /v2/cs/{cb_id} and confirm the connector shows preparing before calling transactions. On an OCPP 2.0.1 or 2.1 station the plug-in starts a transaction by itself once the CSMS has accepted the EV's idTag in Authorize (the connector then shows Occupied, never preparing), and a RequestStartTransaction that reaches the station after that is Rejected because the EVSE already has a transaction. To test a CSMS remote start, send it before the EV is plugged in.

Request

Response

HTTP 200 OK
{}

Errors

• 404 {"error": "EV-01 not found"}
• 404 {"error": "CP-001 not found"}
• 409 {"error": "Simulator CP-001 is still connecting to the CSMS. ...", "connectionStatus": "connecting"}: the station was created but has not connected to your CSMS yet. Wait for the Retry-After header (seconds) and call again
• 409 {"error": "EV-01 is already connected"}

Example

curl -X POST https://api.simitnow.com/v2/ev/EV-01/connection   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"cbId":"CP-001","connectorId":1}'

Disconnect Electric Vehicle

Unplug the EV from its current connector. No request body.

Response

HTTP 200 OK
{}

Errors

• 404 {"error": "EV-01 not found"}

Example

curl -X DELETE https://api.simitnow.com/v2/ev/EV-01/connection   -H "SIMITNOW-API-KEY: <your-key>"

Discharge Electric Vehicle

Manually remove energy from the EV's battery, lowering its state of charge.

Request

Response

HTTP 200 OK
{}

Errors

• 404 {"error": "EV-01 not found"}

Example

curl -X POST https://api.simitnow.com/v2/ev/EV-01/discharge   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"power":5000}'

Create CSMS Instance

Provision your account's own hosted Central System (CSMS) instance that speaks OCPP 1.6, 2.0.1 and 2.1. It is the reverse direction from everything above: instead of SimItNow simulating a station and dialing out to your CSMS, a real or simulated chargepoint implementation dials in to SimItNow's own CSMS. Idempotent: safe to call more than once, always returns the same csmsId for your account. A new instance is public, so a chargepoint can connect to your address as soon as you have it. Call this endpoint to get your connection details up front or to switch modes.

Every OCPP message to or from a chargepoint connected to your instance counts against your daily message allowance, in both directions and Heartbeats included, from the same count your simulated stations and OCPI calls use. A simulated station connected to your own instance is counted once. Once the allowance and its 10% grace are used up, the CSMS closes the connection with WebSocket close code 4429 and answers a new connection with HTTP 429 until 00:00 UTC.

Your CSMS instance has two modes:

Request

Response

HTTP 200 OK
{"csmsId": "AbCdEf0123456789", "wsHost": "csms.simitnow.com", "public": true, "connectionLimit": 20}

Example

curl -X PUT https://api.simitnow.com/v2/csms   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"public":false}'

Get CSMS Instance Info

Read your CSMS instance's current mode, its connection limit (null when there is none), and how many connections are live against it. No request body.

Response

HTTP 200 OK
{
  "csmsId": "AbCdEf0123456789",
  "wsHost": "csms.simitnow.com",
  "public": true,
  "connectionLimit": 20,
  "activeConnections": 2
}

Errors

• 404 {"error": "No CSMS instance provisioned yet"}

Example

curl -X GET https://api.simitnow.com/v2/csms   -H "SIMITNOW-API-KEY: <your-key>"

Clear CSMS Instance

Remove every chargepoint registered under your CSMS instance. This does not change your csmsId, connection host, or public/private mode — a chargepoint you register afterward (private mode only) gets the exact same wss:// host as before. While your instance is public, clearing it does not stop chargepoints connecting. No request body.

Response

HTTP 200 OK
{"deleted": 3}

Example

curl -X DELETE https://api.simitnow.com/v2/csms   -H "SIMITNOW-API-KEY: <your-key>"

Register Chargepoint

Add a chargepoint to your CSMS instance so it can connect and authenticate — the allow-list entry for the inbound direction. Returns a one-time HTTP Basic Auth password and the full wss:// connection URL; the password is shown only once here and cannot be recovered afterward (only its salted hash is stored). Only works in private mode: a new instance is public, and registering is rejected (409) while it is. Switch first with Create CSMS Instance and {"public": false}. Deliberately v2-only: no v1 equivalent, and no GET info route.

Request

Response

HTTP 201 Created
{
  "cbId": "CP-001",
  "displayName": "Test Rig 1",
  "password": "s3cr3t-shown-once",
  "wsUrl": "wss://csms.simitnow.com/ocpp/AbCdEf0123456789/CP-001"
}

Errors

• 400 {"error": "displayName is required"}
• 409 {"error": "Chargepoint CP-001 is already registered for this account"}
• 409 {"error": "This CSMS instance is public: it has no chargepoint allow-list, ..."} — see Create CSMS Instance; switch to private first if you need an allow-list entry.

Example

curl -X PUT https://api.simitnow.com/v2/csms/cp/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"displayName":"Test Rig 1"}'

Delete Chargepoint

Remove a chargepoint from your CSMS instance's allow-list. Config-only: an already-connected session is not force-disconnected by this call — it ends the next time that chargepoint reconnects and its credentials no longer resolve. While your instance is public, deleting a chargepoint does not stop it connecting; switch to private to enforce the allow-list. No request body.

Response

HTTP 200 OK
{"id": "CP-001"}

Errors

• 404 {"error": "Chargepoint CP-001 not found"}

Example

curl -X DELETE https://api.simitnow.com/v2/csms/cp/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

OCPI: test an eMSP against SimItNow

SimItNow acts as an OCPI 2.2.1 CPO, so you can develop and test an eMSP against it. Your eMSP connects to us directly, with no roaming hub, and your registered OCPP chargepoints sit behind SimItNow's OCPI endpoints.

Base URL

https://ocpi.simitnow.com/ocpi/versions

The OCPI tab of the dashboard shows this URL for your account, together with your OCPI country code and party ID.

Handshake with Token A

1. Generate Token A

   Open the OCPI tab and choose Generate Token A. It is shown once, because only its hash is stored. Generating a new one invalidates the previous Token A.

2. Give your eMSP the versions URL and Token A

   Your eMSP calls GET /ocpi/versions and GET /ocpi/2.2.1 with Authorization: Token <Token A>. A base64 encoded token, as OCPI 2.2.1 sends it, works too.

3. Your eMSP posts its credentials

   It sends POST /ocpi/2.2.1/credentials with its own token, its versions URL and its role. We fetch its versions and endpoints before we accept, so that URL must be reachable on a public https address. The reply carries Token B, which your eMSP uses for every later call, and Token A stops working.

4. Follow the readiness checklist

   The OCPI tab marks each step as passed, failed or not run from the calls it has seen, and lists the last 100 calls with their errors.

What is supported

• Credentials, with Token A for the handshake and Token B afterwards.
• Locations and Tariffs, which your eMSP reads. Each registered chargepoint is one location.
• Tokens, which your eMSP pushes with PUT or PATCH.
• Commands: START_SESSION and STOP_SESSION. RESERVE_NOW, CANCEL_RESERVATION and UNLOCK_CONNECTOR answer NOT_SUPPORTED. On an OCPP 2.x chargepoint START_SESSION is answered ACCEPTED and its CommandResult is NOT_SUPPORTED, and STOP_SESSION answers UNKNOWN_SESSION.
• After START_SESSION, connect an EV to the chargepoint within 5 minutes. The station accepts the remote start at once, but the session only begins when an EV connects, and a session that has not begun by then is marked INVALID.
• Sessions and CDRs, which your eMSP can read and which we also send to it. To receive them, your eMSP must advertise the sessions and cdrs receiver endpoints in its module list.

Limits

Every OCPI call counts as one message against the same daily allowance as your OCPP messages. Free accounts can try OCPI within 500 messages a day, OCPP and OCPI together. A call past the allowance and its 10% grace is refused with HTTP 429. The Solo plan is the plan for real testing: 2,500 messages a day.

An active session is updated about every meter sample (30 seconds by default), and every push counts against the same daily message allowance. Going over the allowance also closes your OCPP chargepoints (WebSocket close code 4429). A session left ACTIVE after that is marked INVALID by a sweep after 6 hours, with no CDR.

Private CSMS required

OCPI needs a private CSMS with registered chargepoints. A chargepoint that connects to an open CSMS has no registration, so it cannot appear as an OCPI location. Switch your CSMS to private, then register each chargepoint:

curl -X PUT https://api.simitnow.com/v2/csms   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"public": false}'

Guide: Full Session Lifecycle Beta

A complete walkthrough using CP-001 and EV-01. Each step shows the curl command and expected response.

1. Create a charging station

   curl -X PUT https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"ws://your-csms:9000","protocol":"ocpp1.6"}'

   {"id": "CP-001"}

   Returns HTTP 201, before the station has connected. The station sends BootNotification as soon as the connection to your CSMS is up. Until then calls that name the station answer 409, so poll GET /v2/cs/CP-001 until it answers 200 before the next steps.

2. Create a virtual EV

   curl -X PUT https://api.simitnow.com/v2/ev/EV-01   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"batteryCapacity":60}'

   {"id": "EV-01"}

   Returns HTTP 201.

3. Connect the EV to the station

   curl -X POST https://api.simitnow.com/v2/ev/EV-01/connection   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"cbId":"CP-001","connectorId":1}'

   {}

   The connector transitions to preparing state asynchronously. Poll GET /v2/cs/CP-001 until the connector shows preparing before proceeding.

4. Start a transaction

   curl -X POST https://api.simitnow.com/v2/cs/CP-001/transactions   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"connectorId":1}'

   {"transactionId": 1}

   Save transactionId. This triggers StartTransaction and begins periodic MeterValues.

5. Poll EV info to observe charging

   curl -X GET https://api.simitnow.com/v2/ev/EV-01   -H "SIMITNOW-API-KEY: <your-key>"

   {"id": "EV-01", "soc": 42.5, "capacityWh": 60000, ...}

   Watch soc rise in real time.

6. Stop the transaction

   curl -X DELETE https://api.simitnow.com/v2/cs/CP-001/transactions/1   -H "SIMITNOW-API-KEY: <your-key>"

   {}

   The transaction ID is in the URL path; no request body needed. This triggers StopTransaction to the CSMS.

7. Disconnect the EV

   curl -X DELETE https://api.simitnow.com/v2/ev/EV-01/connection   -H "SIMITNOW-API-KEY: <your-key>"

   {}

8. Clean up

   curl -X DELETE https://api.simitnow.com/v2/ev/EV-01   -H "SIMITNOW-API-KEY: <your-key>"
   curl -X DELETE https://api.simitnow.com/v2/cs/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

   {"id": "EV-01"}
   {"id": "CP-001"}

Authentication

Every request to the SimItNow API must include your API key in the SIMITNOW-API-KEY header. No request body is needed for authentication; it is checked on every call automatically.

Example

curl -X GET https://api.simitnow.com/v1/cs/info/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Create Charging Station

Same parameters as v2, including authorizeLocalStart (a value that is not true or false returns 400), except iccid and imsi, which only v2 takes. This is the endpoint to build against today; v2 is still in beta.

Add ?probe=1 to check the CSMS is reachable before the station is created. On failure nothing is created and the call returns HTTP 422 with the same diagnosis body as the probe endpoint. It is opt-in on purpose: the probe can take up to 8 seconds, so making it unconditional would turn a bulk create of several hundred stations into hours. Leave the flag off for batch work and pass it when you are wiring up a station by hand.

A call that names the station before it has connected to your CSMS answers HTTP 409 with connectionStatus set to connecting and a Retry-After header in seconds. Wait that long and call again, or poll Get Charging Station Info until it answers 200. Deleting the station works at any time.

Example

curl -X POST https://api.simitnow.com/v1/cs/create/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"csmsUrl":"ws://your-csms:9000","protocol":"ocpp1.6"}}'

Connection Security

The v1 create endpoint accepts the same security object as v2. Use it to control the outbound WebSocket connection from the simulated station to your CSMS.

SimItNow also supports OCPP 1.6 Security Whitepaper messages for CSMS testing: GetLog, InstallCertificate, CertificateSigned, DeleteCertificate, GetInstalledCertificateIds, ExtendedTriggerMessage, SignCertificate, SecurityEventNotification, and LogStatusNotification.

SP-1 Example

curl -X POST https://api.simitnow.com/v1/cs/create/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"ws://your-csms:9000","protocol":"ocpp1.6","security":{"basicAuth":{"password":"secret"}}}'

SP-3 Example

curl -X POST https://api.simitnow.com/v1/cs/create/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{"csmsUrl":"wss://your-csms:9443","protocol":"ocpp1.6","security":{"clientCert":{"certificate":"-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
","privateKey":"-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
"}}}'

Get Charging Station Info

Retrieve configuration and connector state of a running station. Use GET /v2/cs/{cb_id} for new integrations.

Example

curl -X GET https://api.simitnow.com/v1/cs/info/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Delete Charging Station

Stop and remove a simulated charging station. Use DELETE /v2/cs/{cb_id} for new integrations.

Example

curl -X POST https://api.simitnow.com/v1/cs/delete/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Transaction Start

Start a charging transaction. Body: connectorId (required), idTag (optional).

On OCPP 2.0.1 and 2.1 the station first sends Authorize and starts the transaction only if your CSMS answers Accepted. If it does not, the answer is still HTTP 200 with result set to False and transaction_id null, plus an error field and, when the CSMS refused, an authorizationStatus field. Without an idTag the station uses the idTag of the plugged-in EV, or 1QAZ2wsx. To skip Authorize, create the station with authorizeLocalStart set to false, or set AuthCtrlr.Enabled to false with SetVariables.

A start that is refused because the EVSE already has a transaction, because the connector is Faulted or Unavailable, or because TxStartPoint has no Authorized and no EV is plugged in, is answered the same way: HTTP 200, result False, an error field, and runningTransactionId or connectorStatus where they apply.

Example

curl -X POST https://api.simitnow.com/v1/cs/transaction/start/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"connectorId":1}}'

Transaction Stop

Stop an active charging transaction. Body: transactionId.

Example

curl -X POST https://api.simitnow.com/v1/cs/transaction/stop/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"transactionId":1}}'

Error Set

Put a connector into a faulted state. Body: connectorId, errorCode.

Example

curl -X POST https://api.simitnow.com/v1/cs/error/set/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"connectorId":1,"errorCode":"HighTemperature"}}'

Error Reset

Clear a faulted connector. Body: connectorId. On OCPP 1.6 the connector reports Available, and then Preparing again if an EV is still plugged in. On OCPP 2.0.1 and 2.1 it reports Occupied if an EV is still plugged into it, and Available if not.

Example

curl -X POST https://api.simitnow.com/v1/cs/error/reset/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"connectorId":1}}'

Security Event

Make the station send an OCPP 1.6 SecurityEventNotification. Body: type (required, up to 50 characters), techInfo (optional, up to 255).

Example

curl -X POST https://api.simitnow.com/v1/cs/security_event/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"type":"TamperDetectionActivated","techInfo":"enclosure sensor 3"}}'

Network Disconnect

Drop the WebSocket connection. Optional body: duration (seconds to stay disconnected).

Example

curl -X POST https://api.simitnow.com/v1/cs/network/disconnect/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Network Connect

Trigger an immediate reconnect attempt. No request body.

Example

curl -X POST https://api.simitnow.com/v1/cs/network/connect/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

Create Electric Vehicle

Same parameters as v2. Use POST /v2/ev/{ev_id} for new integrations.

Example

curl -X POST https://api.simitnow.com/v1/ev/create/EV-01   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"batteryCapacity":60}}'

Get Electric Vehicle Info

Retrieve current state of a virtual EV. Use GET /v2/ev/{ev_id} for new integrations.

Example

curl -X GET https://api.simitnow.com/v1/ev/info/EV-01   -H "SIMITNOW-API-KEY: <your-key>"

Delete Electric Vehicle

Remove a virtual EV. Use DELETE /v2/ev/{ev_id} for new integrations.

Example

curl -X POST https://api.simitnow.com/v1/ev/delete/EV-01   -H "SIMITNOW-API-KEY: <your-key>"

Connect Electric Vehicle

Plug an EV into a connector. Body: cbId, connectorId.

Example

curl -X POST https://api.simitnow.com/v1/ev/connect/EV-01   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"cbId":"CP-001","connectorId":1}}'

Disconnect Electric Vehicle

Unplug the EV from its current connector. No request body.

Example

curl -X POST https://api.simitnow.com/v1/ev/disconnect/EV-01   -H "SIMITNOW-API-KEY: <your-key>"

Discharge Electric Vehicle

Manually remove energy from the EV battery. Body: power (Wh to remove).

Example

curl -X POST https://api.simitnow.com/v1/ev/discharge/EV-01   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"power":5000}}'

Guide: Full Session Lifecycle

A complete walkthrough using CP-001 and EV-01 with v1 endpoints.

1. Create a charging station

   curl -X POST https://api.simitnow.com/v1/cs/create/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"csmsUrl":"ws://your-csms:9000","protocol":"ocpp1.6"}}'

   {"result": "Simulator CP-001 is created"}

2. Create a virtual EV

   curl -X POST https://api.simitnow.com/v1/ev/create/EV-01   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"batteryCapacity":60}}'

   {"result": "Created EV-01"}

3. Connect the EV to the station

   curl -X POST https://api.simitnow.com/v1/ev/connect/EV-01   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"cbId":"CP-001","connectorId":1}}'

   {"result": "EV-01 is connected to CP-001 connector 1"}

   Poll GET /v1/cs/info/CP-001 until the connector shows preparing.

4. Start a transaction

   curl -X POST https://api.simitnow.com/v1/cs/transaction/start/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"connectorId":1}}'

   {"result": "True", "transaction_id": 1}

5. Poll EV info to observe charging

   curl -X GET https://api.simitnow.com/v1/ev/info/EV-01   -H "SIMITNOW-API-KEY: <your-key>"

   {"id": "EV-01", "soc": 42.5, "capacityWh": 60000, ...}

6. Stop the transaction

   curl -X POST https://api.simitnow.com/v1/cs/transaction/stop/CP-001   -H "SIMITNOW-API-KEY: <your-key>"   -H "Content-Type: application/json"   -d '{{"transactionId":1}}'

   {"result": "True"}

7. Disconnect the EV

   curl -X POST https://api.simitnow.com/v1/ev/disconnect/EV-01   -H "SIMITNOW-API-KEY: <your-key>"

   {"result": "EV-01 is disconnected from CP-001 connector 1"}

8. Clean up

   curl -X POST https://api.simitnow.com/v1/ev/delete/EV-01   -H "SIMITNOW-API-KEY: <your-key>"
   curl -X POST https://api.simitnow.com/v1/cs/delete/CP-001   -H "SIMITNOW-API-KEY: <your-key>"

   {"result": "Deleted EV-01"}
   {"result": "Simulator CP-001 is deleted"}