Introduction#

This is a usage guide for our API available at api.switchgrid.tech. An OpenAPI specification is also available.

The following endpoints are still accessible at app.switchgrid.tech/enedis/v2:

We will progressively provide equivalent endpoints in /v0_1, but from now on, consent requests (asks) created with /v0_1 can be used with /enedis/v2 orders.

See the API v2 Guide for Enedis-specific API documentation.

Authentication#

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

All requests must include the x-api-version: v0 header to target this version of the API.

curl https://api.switchgrid.tech/ask \
  -H "Authorization: Bearer <Token>" \
  -H "x-api-version: v0"
⚠️

Warning, this API token is a secret. It allows requesting Enedis consumption data. It is therefore advisable not to disclose it, and thus to make API calls from a server, not from a browser or mobile client.

Collecting User Consent#

Create your first Ask with POST/ask#

Here's an example of the POST/ask request body for an Ask with a gas contract and an electricity contract from GET/search_contractenedis-v2 (old endpoint).

POST/ask
Authorization
Bearer
x-api-version
v0
switchgrid-test-env
true
Enter a token to send requests

Contract proof submission#

When GET/search_contractenedis-v2 (old API) cannot find a contract (e.g., due to a name difference in the supplier's database, 2-letter names, etc.), you can still create an Ask and then upload a proof — typically an electricity bill — to prove the connection between the contract holder and the concerned delivery point.

Process#

1

Create an Ask

Create an Ask via POST/ask as usual. If the contract cannot be found, the Ask status will be NOT_VALID and the contract status will be NOT_FOUND.

{
  "contracts": [
    {
      "_energyType": "electricity",
      "deliveryPointId": "09284757283947",
      "holder": {
        "_tag": "NaturalPerson",
        "fullName": "Jean Dupont"
      },
      "address": {
        "rueEtNumero": "17 avenue Charles de Gaulle",
        "codePostal": "75007",
        "commune": "Paris"
      }
    }
  ],
  "consentDuration": "1 year"
}
ℹ️

This cannot be used with old Asks created via POST/askenedis-v2.

2

Upload an ownership proof

Upload an electricity bill for the failed contract(s) via POST/ask/{askId}/ownership_proof.

Send a multipart/form-data request with the proof file (PDF or image) in the file field.

⚠️

The bill must be recent (less than 3 months) and must contain the PDL number corresponding to the one provided in the Ask.

3

Verification

Switchgrid performs a manual or automatic verification: we check that the PDL provided by the user appears in the document, and that the contract holder and address match the proof.

During these verifications, the status of the Ask contract(s) is PENDING_PROOF_VERIFICATION.

4

Result

Once approved or rejected, a webhook is sent with the event:

  • _tag: "proof.accepted" or _tag: "proof.rejected"
  • Accompanied by askId and organizationId.

If everything is correct, the contract is validated and the Ask continues its process. Otherwise, the user is invited to verify or contact support.

Retrieving Data#

Once an Ask is signed, you can order data:

  • from the old endpoints in the enedis-v2 API
  • from the endpoints of this API version under the /integration path, for Enedis, GRDF and Strasbourg Électricité Réseaux. See details below.
🧪

We are currently working on new v0 version endpoints to allow collecting data in a unified way across different data sources. In the meantime, you can use the old Enedis endpoints with asks created in v0, and for GRDF and ESR, you can use the imperative endpoints described below.

Enedis#

It is still necessary to use /enedis/v2 (old endpoint) for this. You must use the order syntax with prms in each request.

ℹ️

Note to early Switchgrid users:

No need to specify a consentId, we automatically search for corresponding Asks in the old and new API.

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

GRDF#

To order GRDF daily indexes, use the following.

ℹ️

Terminology:

Here we use the term pce instead of deliveryPointId because this endpoint is specific to GRDF, and this is GRDF's vocabulary.

{
  "pce": "00000000000001"
}

Body of POST/integration/grdf-adict/donnees-informatives

Strasbourg Électricité Réseaux (ESR)#

Endpoints#

POST/integration/esr/contract#

Purpose: Detailed metadata of the contract associated with the ESR delivery point, including contract status and contractual 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"
    }
}

POST/integration/esr/maximum-powers#

Purpose: Retrieves maximum power values recorded 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"
        }
    ]
}

POST/integration/esr/meter-readings#

Purpose: Retrieves 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": 2897#63,
            "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"
        }
    ]
}

POST/integration/esr/average-powers#

Purpose: Returns the load curve for the requested RTPL, direction and time interval.

❗

C5 / C6 Load Curve Activation

For C5 and C6 segments, the load curve is not activated by default during consent. We request load curve activation during the consent process (Ask), but it can take up to a week before data becomes available. In the meantime:

  • Calls to this endpoint may return an error indicating that the load curve is not yet available.
  • Clients must implement a retry strategy or status check while waiting for 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 behavior and allow you to validate your integration with different contractual configurations.

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

1. 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:

This scenario represents a fully operational C5 delivery point.

2. C5 – Load curve pending activation#

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

  • RTPL: ESR00000C50002

Expected behavior:

  • The call to POST/integration/esr/average-powers returns an error indicating that ESR has been requested to activate the load curve, and that the activation process can take up to a week.

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

3. C4 – Standard contract#

Use the following RTPL to simulate a C4 contract:

  • RTPL: ESR00000C40001

Expected behavior:

This scenario represents a fully operational C4 delivery point.

SWITCHGRID
© 2026 Switchgrid. All rights reserved.