NetworkCore Contact us

DP API reference

One API for distribution partners such as mobility apps, fleets and car makers: find chargers, show current availability and prices, start and stop charging, follow every session live.

Test first in the Sandbox. Simulated stations, no real money.

   
Base URL https://dp.networkcore.org
Auth Authorization: Bearer <api_key>
Format JSON, amounts incl. VAT, ISO 8601 UTC

Integration levels

A read API key gives Data, a write key gives Full charging. Keys start with nc_live_, or nc_test_ for the Sandbox.

Group Data Full charging
Locations and availability ✓ ✓
Prices ✓ ✓
Data webhooks ✓ ✓
Sessions   ✓
Live session updates   ✓
Payments (optional)   ✓
Pay after charging (optional)   ✓
Receipts and tax invoices (optional)   ✓
Disputes (optional)   ✓
Station feedback (optional)   ✓

Conventions

Your reference

Every session carries reference: your own order or transaction ID. It is required, unique per partner, and comes back on every session, webhook, tax invoice and dispute. Sending the same reference twice replays the first answer instead of starting a second charge.

Charging partner

The company that runs the chargers. Locations show it as charging_partner.

Charge point status

Every charge point has one of these statuses, passed on as the charging partner reports it. It can lag by up to about 30 seconds.

Status Meaning
AVAILABLE Free to start a charge
CHARGING A charge is running, or a vehicle was just plugged in (depends on the charging partner)
BLOCKED Occupied without charging, for example a parked or just-plugged vehicle
RESERVED Reserved for a driver
INOPERATIVE Not working at the moment
OUTOFORDER Out of order
PLANNED Planned for the future
UNKNOWN Status not known
REMOVED Removed by the charging partner. Never returned: the charge point no longer appears.

A vehicle that was just plugged in shows as BLOCKED or CHARGING before its session starts, depending on the charging partner.

Errors

One shape everywhere:

{ "error": { "code": "CHARGE_POINT_OCCUPIED",
             "message": "Charge point EVSE-01 already has an active session." } }

A missing or invalid key returns 401 UNAUTHORIZED. A read key on a write endpoint returns 403 FORBIDDEN. A blocked partner gets 403 DP_BLOCKED everywhere except reading and stopping its sessions and POST /payments. Too many requests returns 429.

Headers

Lists and syncing

Webhooks

Setup. Ask NetworkCore to register one HTTPS endpoint for you. You get a signing secret (starts with whsec_), shown once. All events go to that endpoint.

Payload. Every event has id, type, created_at and data. Session events carry the same body as GET /sessions/{id}:

{
  "id": "evt_01J9XK2",
  "type": "session.completed",
  "created_at": "2026-10-01T16:12:44Z",
  "data": {
    "id": "ses_7Hq2Lx",
    "reference": "ORDER-20261001-000231",
    "status": "COMPLETED",
    "location_id": "LOC-CDMX-0142",
    "charge_point_id": "MX*EXA*E0142A",
    "physical_reference": "A1",
    "connector_id": "1",
    "start_time": "2026-10-01T15:30:41Z", "end_time": "2026-10-01T16:12:30Z",
    "kwh": 40.2, "currency": "MXN",
    "total_cost": 372.78, "total_cost_status": "FINAL",
    "cost_breakdown": [{ "type": "ENERGY", "amount": 357.78 }, { "type": "FLAT", "amount": 15.00 }],
    "receipt_url": "https://dp.networkcore.org/sessions/ses_7Hq2Lx/receipt",
    "tax_invoice": { "status": "ISSUED", "url": "https://dp.networkcore.org/sessions/ses_7Hq2Lx/tax_invoice" },
    "created_at": "2026-10-01T15:30:02Z",
    "updated_at": "2026-10-01T16:12:44Z"
  }
}

receipt_url and tax_invoice (coming soon)

Verifying signatures. We follow the Standard Webhooks spec. Each request carries three headers: webhook-id, webhook-timestamp and webhook-signature. The signature is an HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body} using your secret, base64-encoded and prefixed with v1,. Use the official Standard Webhooks library for your language, or compute it yourself. Reject requests whose timestamp is more than 5 minutes old.

import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.NETWORKCORE_WEBHOOK_SECRET);
const event = wh.verify(rawBody, headers); // throws if the signature is invalid

Delivery rules.

Settlement and reconciliation

Every session carries your reference and its final amounts, so you can match it in your own system. Settlements and session detail are in the NetworkCore portal, with CSV export. A Settlement API is available on request.

Examples

IDs, tax IDs and amounts in examples are illustrative.

Session lifecycle

PENDING → ACTIVE → COMPLETED
        ↘ FAILED
Status Meaning
PENDING We sent the start to the charger and are waiting for it to confirm
ACTIVE Energy is flowing
COMPLETED Charging ended. The final cost may come later: see total_cost_status.
FAILED The charger refused or never confirmed

Locations and availability

GET /locations

Chargers near a point or inside a map area, with current status.

Optional parameters
Query Meaning
lat, lng, radius_km Search around a point
bbox Or a map area: min_lng,min_lat,max_lng,max_lat
country ISO code, e.g. MX
min_power_kw e.g. 50 for fast charging
connector CCS2, TYPE2, CHADEMO, GBT…
available_only true to match only AVAILABLE charge points
updated_since Only locations changed since this time
limit, offset Paging
{
  "data": [{
    "id": "LOC-CDMX-0142",
    "name": "Example Plaza, Level 2",
    "charging_partner": { "id": "MX*EXA", "name": "Example CPO" },
    "address": "Av. Ejemplo 100, Ciudad de México",
    "coordinates": { "lat": 19.4402, "lng": -99.2038 },
    "country": "MX", "time_zone": "America/Mexico_City",
    "payment_url": "https://pay.example.com/l/LOC-CDMX-0142",
    "charge_points": [{
      "id": "MX*EXA*E0142A",
      "evse_id": "MX*EXA*E0142*1",
      "physical_reference": "A1",
      "status": "AVAILABLE",
      "payment_url": "https://pay.example.com/c/LOC-CDMX-0142/MX*EXA*E0142A",
      "connectors": [{ "id": "1", "standard": "CCS2", "power_kw": 120, "tariff_id": "EXA-DC-PUB" }]
    }],
    "last_updated": "2026-10-01T15:04:11Z"
  }],
  "total_count": 1, "limit": 50, "offset": 0
}

payment_url is on the location and on each charge point. It is a link where a driver can pay for and start a charging session there, or null when payment is not available for it. Use the URL as published; do not build or rewrite it.

evse_id is the charging partner’s own ID for the charge point, for display. physical_reference is the number or label printed on the charge point. Both are null when the charging partner does not send them. Use id to refer to a charge point.

GET /locations/{id}

One location with all its charge points, connectors, status and tariffs. Same shape as an item in GET /locations.

Errors: LOCATION_NOT_FOUND

GET /availability

Light status feed for keeping a map fresh without re-downloading locations. status uses the same values as Charge point status.

Query Meaning
updated_since required Status changes since this time
Optional parameters
Query Meaning
limit, offset Paging
{
  "data": [
    { "location_id": "LOC-CDMX-0142", "charge_point_id": "MX*EXA*E0142A",
      "status": "CHARGING", "changed_at": "2026-10-01T15:21:40Z" }
  ],
  "total_count": 1, "limit": 500, "offset": 0
}

Prices

GET /tariffs

Every CPO tariff on the network, as structured price components. Prices are what you pay under your agreement, VAT included.

Optional parameters
Query Meaning
updated_since Only tariffs changed since this time
limit, offset Paging
{
  "data": [{
    "id": "EXA-DC-PUB",
    "currency": "MXN",
    "elements": [{
      "components": [
        { "type": "ENERGY", "price": 8.90, "unit": "kWh" },
        { "type": "FLAT",   "price": 15.00, "unit": "session" }
      ],
      "restrictions": { "start_time": "06:00", "end_time": "22:00", "day_of_week": null }
    }],
    "last_updated": "2026-09-28T10:00:00Z"
  }],
  "total_count": 38, "limit": 50, "offset": 0
}

GET /tariffs/{id}

One tariff. Same shape as an item in GET /tariffs.

Errors: TARIFF_NOT_FOUND

POST /quotes

What a charge will cost your driver at this connector, with your agreement applied.

Body field Meaning
location_id required  
charge_point_id required The charge point’s id as returned by GET /locations
connector_id required  
estimate.kwh Expected energy, e.g. 40. Needed when the price is per kWh.
estimate.minutes Expected duration. Needed for time-based prices.
{
  "data": {
    "currency": "MXN",
    "pricing_mode": "PUBLIC",
    "total_incl_vat": 371.00,
    "breakdown": [
      { "type": "ENERGY", "quantity": 40, "unit": "kWh", "amount": 356.00 },
      { "type": "FLAT",   "quantity": 1,  "unit": "session", "amount": 15.00 }
    ],
    "valid_until": "2026-10-01T16:00:00Z"
  }
}

pricing_mode is PUBLIC, PUBLIC_DISCOUNT, PUBLIC_FIX or WHOLESALE.

Error HTTP
MISSING_FIELD (a body field, or the estimate the price needs) 422
INVALID_PARAMETER 422
NO_AGREEMENT 422
NO_TARIFF 422
LOCATION_NOT_FOUND 404
CHARGE_POINT_NOT_FOUND 404
CONNECTOR_NOT_FOUND 404
AMBIGUOUS_LOCATION (location_id belongs to more than one charging partner) 409
LOCATION_BLOCKED 409

Data webhooks

Event When
evse.status_changed A charge point’s status changed. Same item as GET /availability.
location.updated A location was added, changed or removed. Carries location_id; read GET /locations/{id}.
tariff.updated A CPO changed a price. Carries tariff_id; read GET /tariffs/{id}.

Sessions

POST /sessions

Start charging. We send the start command to the charger. Send the charge point the driver chose, or let us detect it: see Plug in, tap Start.

Body field Meaning
reference required Your order ID. Unique per partner. Same reference = same answer.
location_id required  
charge_point_id required, unless detected The charge point’s id as returned by GET /locations. Leave out to let us detect it (coming soon).
connector_id required, unless detected  
driver_ref required The person or account paying. Keep it stable across sessions and cars.
Optional fields
Body field Meaning
billing_details (coming soon) Send the driver’s tax data and the tax invoice is issued automatically when the session completes. Same fields as PUT /sessions/{id}/billing_details.
plugged_at (coming soon) When the car was plugged in, ISO 8601, as the car reports it. Recommended when you leave out charge_point_id.
connector (coming soon) The car’s connector, same values as GET /locations (CCS2, TYPE2, CHADEMO, GBT…). Used only when we detect the charge point.
HTTP 201
{
  "data": {
    "id": "ses_7Hq2Lx",
    "reference": "ORDER-20261001-000231",
    "status": "PENDING",
    "location_id": "LOC-CDMX-0142",
    "charge_point_id": "MX*EXA*E0142A",
    "physical_reference": "A1",
    "connector_id": "1",
    "start_time": null, "end_time": null,
    "kwh": 0, "currency": "MXN", "total_cost": null, "total_cost_status": null,
    "cost_breakdown": null,
    "created_at": "2026-10-01T15:30:02Z",
    "updated_at": "2026-10-01T15:30:02Z"
  }
}
Error HTTP
MISSING_FIELD 422
DUPLICATE_REFERENCE (same reference, different request) 422
NO_AGREEMENT 422
NO_TARIFF 422
LOCATION_NOT_FOUND 404
CHARGE_POINT_NOT_FOUND 404
CONNECTOR_NOT_FOUND 404
CHARGE_POINT_OCCUPIED 409
CHARGE_POINT_NOT_DETECTED (coming soon: we could not tell which charge point the car is plugged into; the error lists candidates) 409
AMBIGUOUS_LOCATION (location_id belongs to more than one charging partner) 409
LOCATION_BLOCKED 409
REQUEST_IN_PROGRESS 409
TOKEN_ERROR (driver could not be authorized at the charging partner) 502
SESSION_START_FAILED 502
PRICING_UNAVAILABLE (could not price the session, retry shortly) 503
BLOCKS_UNAVAILABLE (could not check whether the charge point is blocked, retry shortly) 503

Plug in, tap Start (coming soon)

For car makers and apps that know when the car is plugged in. The driver plugs in and taps Start. No charger to pick.

  1. Find the location from the car’s GPS once: GET /locations?lat=19.4402&lng=-99.2038&radius_km=0.2.
  2. When the driver taps Start, call POST /sessions with reference, location_id, driver_ref, plugged_at and connector, without charge_point_id.
  3. We find the charge point that turned occupied when the car was plugged in, and start it. Show the driver “Charging at {physical_reference}”.
  4. If we can’t tell which one, you get 409 CHARGE_POINT_NOT_DETECTED with candidates. Show them, then send the driver’s pick with the same reference and its charge_point_id. Don’t resend the same request.
HTTP 409
{
  "error": {
    "code": "CHARGE_POINT_NOT_DETECTED",
    "message": "Could not tell which charge point the car is plugged into.",
    "candidates": [
      { "charge_point_id": "MX*EXA*E0142A", "connector_id": "1", "physical_reference": "A1", "status": "BLOCKED" },
      { "charge_point_id": "MX*EXA*E0142B", "connector_id": "1", "physical_reference": "A2", "status": "AVAILABLE" }
    ]
  }
}

Safety. If the car sees no current within 60 seconds of session.started, call POST /sessions/{id}/stop.

Several cars, one account. Send the same driver_ref. Each car’s request is matched on its own.

GET /sessions/{id}

One session, live: energy so far, cost so far, status. total_cost_status is ESTIMATED while charging and until the charger’s final record arrives, FINAL once it is confirmed, IN_REVIEW while we check it (total_cost is null), or NO_CDR if the record never came (total_cost is the last estimate).

{
  "data": {
    "id": "ses_7Hq2Lx",
    "reference": "ORDER-20261001-000231",
    "status": "COMPLETED",
    "location_id": "LOC-CDMX-0142",
    "charge_point_id": "MX*EXA*E0142A",
    "physical_reference": "A1",
    "connector_id": "1",
    "start_time": "2026-10-01T15:30:41Z", "end_time": "2026-10-01T16:12:30Z",
    "kwh": 40.2, "currency": "MXN",
    "total_cost": 372.78, "total_cost_status": "FINAL",
    "cost_breakdown": [{ "type": "ENERGY", "amount": 357.78 }, { "type": "FLAT", "amount": 15.00 }],
    "receipt_url": "https://dp.networkcore.org/sessions/ses_7Hq2Lx/receipt",
    "tax_invoice": { "status": "ISSUED", "url": "https://dp.networkcore.org/sessions/ses_7Hq2Lx/tax_invoice" },
    "created_at": "2026-10-01T15:30:02Z",
    "updated_at": "2026-10-01T16:12:44Z"
  }
}

cost_breakdown: what total_cost is made of, once FINAL. null before that.

receipt_url and tax_invoice (coming soon)

Errors: SESSION_NOT_FOUND 404

GET /sessions

Your sessions.

Optional parameters
Query Meaning
status PENDING, ACTIVE, COMPLETED, FAILED
updated_since Only sessions changed since this time
limit, offset Paging

POST /sessions/{id}/stop

Stop charging. Returns 202 while the charger confirms.

Error HTTP
SESSION_NOT_FOUND 404
SESSION_NOT_ACTIVE 409
SESSION_NOT_LINKED (charger has not reported the session yet, retry shortly) 409
SESSION_STOP_FAILED 502

PUT /sessions/{id}/retail_total (coming soon)

Wholesale partners only: the price you charged your driver.

Body field Meaning
amount required Incl. VAT
currency required  

Live session updates

Every change to a running session reaches you as a webhook, and GET /sessions/{id} always returns the latest state.

Event When
session.started · session.updated · session.completed · session.failed Live session events. session.updated whenever kWh or cost so far changes.
{
  "id": "evt_01J9XK2",
  "type": "session.completed",
  "created_at": "2026-10-01T16:12:44Z",
  "data": {
    "id": "ses_7Hq2Lx",
    "reference": "ORDER-20261001-000231",
    "status": "COMPLETED",
    "location_id": "LOC-CDMX-0142",
    "charge_point_id": "MX*EXA*E0142A",
    "physical_reference": "A1",
    "connector_id": "1",
    "start_time": "2026-10-01T15:30:41Z", "end_time": "2026-10-01T16:12:30Z",
    "kwh": 40.2, "currency": "MXN",
    "total_cost": 372.78, "total_cost_status": "FINAL",
    "cost_breakdown": [{ "type": "ENERGY", "amount": 357.78 }, { "type": "FLAT", "amount": 15.00 }],
    "receipt_url": "https://dp.networkcore.org/sessions/ses_7Hq2Lx/receipt",
    "tax_invoice": { "status": "ISSUED", "url": "https://dp.networkcore.org/sessions/ses_7Hq2Lx/tax_invoice" },
    "created_at": "2026-10-01T15:30:02Z",
    "updated_at": "2026-10-01T16:12:44Z"
  }
}

receipt_url and tax_invoice (coming soon)

Payments (optional)

Tell us which sessions you collected from drivers, so we can match your payment to them. Needs a write key.

POST /payments

Body field Meaning
reference required Your own ID for this payment, up to 200 characters
paid_at required When you collected it, ISO 8601
currency required ISO 4217, e.g. MXN
sessions required 1 to 100 items, each with session_id and amount
{
  "reference": "PAY-2026-10-03-001",
  "paid_at": "2026-10-03T09:00:00Z",
  "currency": "MXN",
  "sessions": [{ "session_id": "ses_7Hq2Lx", "amount": 372.78 }]
}

Returns 201 with the stored payment and received_at. Sending the same reference and body again returns 200 with what was stored.

Error HTTP
INVALID_PARAMETER 422
INVALID_SESSIONS (a session is unknown or in another currency; nothing is stored) 422
REFERENCE_REUSED (same reference, different body) 409
Pay after charging (optional, coming soon)

Charge the driver after each session. If a payment fails, tell us and we pause charging for that driver until it’s paid.

Receipts and tax invoices (optional, coming soon)

Every public price session gets a receipt automatically. The tax invoice is issued automatically once you send the driver’s billing details, at session start or afterwards. For wholesale sessions you are the seller, so you issue your own.

GET /sessions/{id}/receipt (coming soon)

Returns the receipt PDF.

PUT /sessions/{id}/billing_details (coming soon)

Send or correct the driver’s tax data.

Body field Meaning
tax_id required e.g. RFC in Mexico
legal_name required  
postal_code required  
tax_regime required in Mexico  
invoice_use required in Mexico  
email Where to send the tax invoice
country ISO code, e.g. MX
{
  "data": {
    "session_id": "ses_7Hq2Lx",
    "reference": "ORDER-20261001-000231",
    "tax_invoice": { "status": "REQUESTED" }
  }
}
Error HTTP
INVALID_BILLING_DETAILS 422
TAX_INVOICE_NOT_AVAILABLE (wholesale session) 409
TAX_INVOICE_ALREADY_ISSUED 409
SESSION_NOT_FOUND 404

GET /sessions/{id}/tax_invoice (coming soon)

Returns the tax invoice PDF once issued.

Error HTTP
TAX_INVOICE_NOT_READY 409
SESSION_NOT_FOUND 404

Event tax_invoice.issued (coming soon)

Carries reference and the tax invoice url.

Disputes (optional, coming soon)

POST /sessions/{id}/disputes (coming soon)

Report a refund, chargeback or wrong charge on a session.

Body field Meaning
type required REFUND, CHARGEBACK, BILLING_ERROR
amount required Disputed amount
reason  
{
  "data": {
    "id": "dsp_31Kc",
    "session_id": "ses_7Hq2Lx",
    "reference": "ORDER-20261001-000231",
    "type": "CHARGEBACK",
    "amount": 120.00,
    "currency": "MXN",
    "status": "UNDER_REVIEW"
  }
}

GET /disputes/{id} (coming soon)

One dispute. status is UNDER_REVIEW, ACCEPTED or REJECTED. Once decided, the response carries the outcome:

{
  "data": {
    "id": "dsp_31Kc",
    "session_id": "ses_7Hq2Lx",
    "reference": "ORDER-20261001-000231",
    "type": "CHARGEBACK",
    "amount": 120.00,
    "currency": "MXN",
    "status": "ACCEPTED",
    "outcome": { "amount": 120.00, "currency": "MXN", "effect": "SET_OFF_NEXT_SETTLEMENT" }
  }
}

Errors: DISPUTE_NOT_FOUND 404

GET /sessions/{id}/evidence (coming soon)

Returns the evidence PDF for a chargeback: session timeline, meter values, the charging partner’s charge record and our checks.

Event dispute.updated (coming soon)

Carries reference, status and outcome.

Station feedback (optional, coming soon)

Let drivers rate a station and report a problem.

GET /feedback/form (coming soon)

The form to show the driver: a rating, the possible problems and the messages. Show it as given.

Query Meaning
language en or es. Default en.
{
  "data": {
    "title": "How was this station?",
    "rating": { "min": 1, "max": 5 },
    "problems_prompt": "Any problem with this station?",
    "problems": [
      { "code": "SECURITY", "label": "Security" },
      { "code": "SPEED", "label": "Charging speed" },
      { "code": "LIGHTING", "label": "Lighting" },
      { "code": "CLEANLINESS", "label": "Cleanliness" },
      { "code": "CONNECTOR", "label": "Damaged cable or connector" },
      { "code": "NOT_WORKING", "label": "Charger not working" },
      { "code": "ACCESS", "label": "Hard to reach or blocked" },
      { "code": "OTHER", "label": "Something else" }
    ],
    "comment_prompt": "Tell us more (optional)",
    "thank_you": "Thanks, your feedback helps drivers and station owners."
  }
}

POST /feedback (coming soon)

Send a driver’s rating of a charge point, after a session or at any time. Needs a write key.

Body field Meaning
location_id required  
charge_point_id required The charge point’s id as returned by GET /locations
driver_ref required Your stable ID for the driver
rating required A whole number from 1 to 5
problems Codes from the form, for example ["LIGHTING"]
comment Free text, up to 500 characters
session_id The session this rating follows, for a rating after charging
{
  "data": {
    "id": "fbk_9Tm4Qa",
    "location_id": "LOC-CDMX-0142",
    "charge_point_id": "MX*EXA*E0142A",
    "rating": 4,
    "problems": ["LIGHTING"],
    "created_at": "2026-10-01T16:20:05Z"
  }
}

Returns 201.

Error HTTP
MISSING_FIELD 422
INVALID_PARAMETER (rating out of range or unknown problem code) 422
LOCATION_NOT_FOUND 404
CHARGE_POINT_NOT_FOUND 404
SESSION_NOT_FOUND 404