Guide API v0.1

🚧

This document is WIP. This API is still beta, please reach us at [email protected] or via Slack if you have questions.

This is a guide to using our API /v0_1. There is also an OpenAPI specification available.

Api is accessible at path app.switchgrid.tech/v0_1.

ℹ️

API /v0_1 is the first version of Switchgrid’s API that supports other DSOs (Distribution System Operator) than Enedis. The first supported DSOs are GRDF and Strasbourg Électricité Réseaux.

Table of contents

Auth Create your first Ask Enedis GRDF Strasbourg Électricité Réseaux (ESR)Endpoints GET /integration/esr/contract GET /integration/esr/maximum-powers GET /integration/esr/meter-readings GET /integration/esr/average-powers Test RTPLs for Integration Useful docs

⚠️

The following API endpoints are still on api.switchgrid.tech/enedis/v2 :

GET /search_contract - search for an Enedis electricity contract

POST /order - post an order for Enedis

We will progressively provide endpoints that match this functionality in /v0_1 but as of now, asks (consents) created with /v0_1 can be used with /enedis/v2 orders. See

Migration from /enedis/v2 to /v0_1 details.

See

API Switchgrid Enedis for documentation of the Enedis-specific api.

Auth

All calls are made with an authentication header Authorization: Bearer <Token>. Tokens can be created / rotated via the interface https://app.switchgrid.tech.

⚠️

Caution, this API token is a secret. It allows you to request Enedis consumption data. It is therefore advised not to reveal it, and thus to make API calls from a server, not from the browser or a mobile client.

Create your first `Ask`

This is an example of the body of POST /v0_1/ask an Ask with a gas contract, and an electricity contract coming from GET /enedis/v2/search_contract.


{
  "contracts": [
    "5a03cc9d-16d3-4045-b540-a0a0a0deda11", // Contract from GET /enedis/v2/search_contract
    {
      "_energyType": "gas",
      "deliveryPointId": "00000000000001",
      "holder": {
        "_tag": "NaturalPerson",
        "fullName": "Jean Dupont"
      },
      "address": {
        "rueEtNumero": "17 avenue Charles de Gaulle",
        "codePostal": "75007",
        "commune": "Paris"
      }
    }
  ],
  "consentDuration": "1 day"
}

body of POST /v0_1/ask

Enedis

It’s still required to use /enedis/v2 for that. You have to use the order syntaxt with prms in every request.

ℹ️

Note to early Switchgrid users :

No need to specify a consentId, we automatically look for matching Asks in both the old and new APIs.


{
  "requests": [
    {
      "type": "LOADCURVE",
      "direction": "CONSUMPTION",
      "prms": ["00046372994792", "00052989142094"]
    },
    {
      "type": "C68_ASYNC",
      "direction": "CONSUMPTION",
      "prms": ["00046372994792", "00052989142094"]
    }
  ]
}

Example of POST /enedis/v2/order

GRDF

For ordering daily indices from GRDF, use the following.

ℹ️

Terminology: Here we use the term pce instead of deliveryPointId because this endpoint is grdf-specific, and that’s the vocabulary of GRDF.


{
  "pce": "00000000000001"
}

body of POST /v0_1/integration/grdf-adict/donnees-informatives

Strasbourg Électricité Réseaux (ESR)

Endpoints

`GET /integration/esr/contract`

Purpose: Detailed contract metadata associated with the ESR supply point, including contract status, and contract identifiers.

Usage

Call this endpoint to retrieve a customer’s contract details once the consent Ask is active.


{
  "rtpl": "..."
}

Response


{
    "rtpl": "...",
    "usagePoint": {
        "usagePointId": "...",
        "usagePointStatus": "COM",
        "meterType": "compteur communicant bleu"
    },
    "contract": {
        "segment": "C5",
        "subscribedPower": "6 kVA",
        "lastActivationDate": "2024-09-12",
        "distributionTariff": "CU ADT 4 postes",
        "contractType": "Contrat unique",
        "contratStatus": "Actif",
        "lastDistributionTariffChangeDate": "2024-09-12",
        "offpeakHours": "23:00-07:00"
    }
}

`GET /integration/esr/maximum-powers`

Purpose: Retrieves the maximum recorded power values for the RTPL over defined periods.

Usage


{
    "rtpl": "...",
    "since": "2023-02-23",
    "until": "2023-02-24"
}

Response


{
    "rtpl": "...",
    "since": "2026-02-23",
    "until": "2026-02-24",
    "count": 1096,
    "data": [
        {
            "value": 2915,
            "pas": null,
            "libelle": null,
            "timestamp": "2026-02-23T08:25:00.000+00:00",
            "timestampStorage": "2026-02-23T08:25:33.409+00:00"
        },    
     ]
}

`GET /integration/esr/meter-readings`

Purpose: Fetches raw meter readings (index values) for the RTPL

Usage


{
    "rtpl": "...",
    "since": "2026-02-23",
    "until": "2026-02-24",
    "type":"fournisseur"
}

Response


{
    "rtpl": "...",
    "since": "2026-02-23",
    "until": "2026-02-24",
    "count": 4384,
    "data": [
        {
            "value": 77818,
            "measureType": "NETWORK_INDEX_02",
            "libelle": "GRD HP BASSE",
            "timestamp": "2026-02-23T00:00:00.000+00:00",
            "timestampStorage": "2026-02-23T00:41:02.079+00:00"
        },
        {
            "value": 37820,
            "measureType": "NETWORK_INDEX_03",
            "libelle": "GRD HC HAUTE",
            "timestamp": "2026-02-23T00:00:00.000+00:00",
            "timestampStorage": "2026-02-23T00:41:02.079+00:00"
        },
        {
            "value": 927210,
            "measureType": "NETWORK_INDEX_01",
            "libelle": "GRD HC BASSE",
            "timestamp": "2026-02-23T00:00:00.000+00:00",
            "timestampStorage": "2026-02-23T00:41:02.079+00:00"
        },
        {
            "value": 289763,
            "measureType": "NETWORK_INDEX_04",
            "libelle": "GRD HP HAUTE",
            "timestamp": "2026-02-23T00:00:00.000+00:00",
            "timestampStorage": "2026-02-23T00:41:02.079+00:00"
        },    
     ]
}

`GET /integration/esr/average-powers`

Pupose: Returns the loadcurve for the requested RTPL, direction and time interval.

❗

C5 / C6 Loadcurve Activation

For segments C5 and C6, the loadcurve is not enabled by default upon consent. We request the loadcurve activation during the consent Ask process, but it may take up to one week before the loadcurve data is available. Until then:

Calls to this endpoint may return an error indicating that the loadcurve is not yet available.

Clients should implement a retry strategy or status check while waiting for the data to be activated.

Usage


{
    "rtpl": "....",
    "since": "2026-01-22T23:00:00.000+00:00",
    "until": "2026-02-23T23:00:00.000+00:00",
    "type":"soutirage"
}

Response


{
    "rtpl": "...",
    "count": 31,
    "since": "2026-01-22T23:00:00.000+00:00",
    "until": "2026-02-23T23:00:00.000+00:00",
    "data": [
			...
    ]
}

Test RTPLs for Integration

The following RTPLs are available to test different contract types and load curve scenarios.

These RTPLs simulate real ESR behaviour and allow you to validate your integration against different contract configurations.

For all the following test cases, you first need to create an Ask for the given RTPL with the switchgrid-test-env set to true, and to sign the Ask yourself.

C5 – Load Curve Already Activated

Use the following RTPL to simulate a C5 contract where the load curve is already activated:

RTPL: ESR00000C50001

Expected behavior:

✅ Calling /esr/average-powers succeeds and returns sample (random) data.

✅ Calling /esr/contract returns contract data compatible with a C5.

✅ Calling /esr/meter-readings succeeds and returns sample (random) data.

✅ Calling /esr/maximum-powers succeeds and returns sample (random) data.

This scenario represents a fully operational C5 supply point.

C5 – Load Curve Pending Activation

Use the following RTPL to simulate a C5 contract where the load curve must be activated:

RTPL: ESR00000C50002

Expected behavior:

❌ Calling /esr/average-powers returns an error indicating that ESR has been requested to activate the load curve, and that the activation process may take up to one week.

This scenario allows you to validate error handling and retry logic while the load curve is pending activation.

C4 – Standard Contract

Use the following RTPL to simulate a C4 contract:

RTPL: ESR00000C40001

Expected behavior:

✅ Calling /esr/average-powers succeeds and returns sample (random) data.

✅ Calling /esr/contract returns contract data compatible with a C4.

✅ Calling /esr/meter-readings succeeds and returns sample (random) data.

✅ Calling /esr/maximum-powers succeeds and returns sample (random) data.

This scenario represents a fully operational C4 supply point.

Useful docs

Migration from /enedis/v2 to /v0_1

Getting started with API v0.1

Auth

Create your first Ask

Enedis

GRDF

Strasbourg Électricité Réseaux (ESR)

Endpoints

GET /integration/esr/contract

GET /integration/esr/maximum-powers

GET /integration/esr/meter-readings

GET /integration/esr/average-powers

Test RTPLs for Integration

Useful docs

Create your first `Ask`

`GET /integration/esr/contract`

`GET /integration/esr/maximum-powers`

`GET /integration/esr/meter-readings`

`GET /integration/esr/average-powers`