Postman Collection: https://www.postman.com/thomas-carli/workspace/switchgrid-public/collection/4602012-cf6b568e-addb-41a9-868d-3e6cbd73eabe

Introduction#

Vocabulary#

Main endpoints#

The following endpoints will allow you to retrieve data from an electricity meter.

• GET /search_contract to search for an electricity contract from a name and address.
• POST /ask to request the collection of user consent (or multiple if multiple PRMs)
  • GET /ask/{askId} to check the status of an Ask, and see the associated Consents.
• POST /order a call to order consumption data, from a Consent or an Ask
  • GET /order/{orderId} to check the status of an Order and collect the associated data after a variable time depending on the data type (a few seconds for contractual information, a few minutes for a load curve over 24 months)
• GET /request/{requestId}/data To retrieve data for LOADCURVE type requests.

Other accessible endpoints#

• GET /ask - List Asks and their status
• GET /order/{orderId} to check the order status and collect data
• DELETE /ask/{askId} to cancel an Ask, and all associated consents

Authentication#

All calls are made with an authentication header containing an API token, (provided by Switchgrid via the interface https://app.switchgrid.tech) of the type Authorization: Bearer <Token>.

Test environment (switchgrid-test-env)#

You can include the following header in your POST /ask requests: switchgrid-test-env: true so that they are not billed. The resulting orders will not be billed either, but they will return dummy data.

Endpoints#

GET /search_contract#

The request takes 2 mandatory parameters:

• name, which must contain at least 3 characters (e.g.: "Dupond" or "Jeanne Dupond", or "SARL Les Tanneurs")
• and at least one of the following two parameters:
  • address which must contain at least one street name element and a postal code. For example: "1 rue de la paix 75002 Paris"
  • prm the PDL (Delivery Point) number

Example response:

{
  "results": [
    {
      "nomClientFinalOuDenominationSociale": "ST DUPONT",
      "prm": "00000000000022",
      "categorieClientFinalCode": "PRO",
      "adresseInstallationNormalisee": {
        "ligne2": "DP TJ TB",
        "ligne4": "10 RUE DE LA PAIX",
        "ligne6": "75002 PARIS"
      }
    }
  ]
}

POST /ask#

The request body consists of:

• electricityContracts can be of 2 different types. Either an array of uuid - results from GET /search_contract (recommended) - or an array of objects containing the data related to the electricity contract(s).

• scopes (optional) can be used to generate the consent-related section in the form.

• purposes (optional) will be used to indicate the purposes in the form

• signer: the person filling out the consent declaration.
• consentDuration: Duration for which consents can be used, from the signature date of the Ask.

Example request:

{
  "electricityContracts": ["7401e757-2216-4cc5-8e51-e7176de67ed6"],
  "signer": {
    "firstName": "Jean",
    "lastName": "lastName"
  },
  "purposes": ["SOLAR_INSTALLATION_SIZING"],
  "consentDuration": "3 years"
}

In response, Switchgrid responds with the identifier and an acknowledgment of the Ask, as well as the form link to be signed.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "PENDING_USER_ACTION",
  "acceptedAt": "2024-06-17T13:40:21.422Z",
  "consentCollectionDetails": {
    "service": "WEB_HOSTED",
    "userUrl": "https://app.switchgrid.tech/c/..."
  },
  "createArgs": {}
}

In the case of web consent (WEB_HOSTED), you can specify additional URL parameters to the URL provided in userUrl:

• redirectTo to redirect the user once the consent is signed.

Once the electronic signature document has been signed, when calling GET /ask/{askId}, status changes to ACCEPTED.

To revoke a previously signed consent, use DELETE /ask/{askId}. For now, it is not possible to revoke only part of the meters.

POST /order#

Once the user has given their consent via an Ask, it is possible to order data via POST /order.

• requests: a list of requests for which the end user has given their consent.

Request types#

The since and until parameters are by default in UTC. They can take the following forms:

2024-12-10
2024-12-10T00:00:00
2024-12-10T12:00:00Z
2024-12-10T00:00:00+01:00
2024-12-10T00:00:00[Europe/Paris]
2024-12-10T00:00:00[CET]

Example request:

{
  "requests": [
    {
      "prms": ["00045855908792"],
      "type": "LOADCURVE",
      "direction": "CONSUMPTION",
      "since": "2024-06-12",
      "until": "2024-06-15"
    },
    {
      "prms": ["00045855908792"],
      "type": "R65"
    }
  ]
}

Response:

{
  "id": "47608cf7-1396-47fa-ada0-087de727b291",
  "status": "PENDING_REQUESTS",
  "requests": [
    {
      "type": "LOADCURVE",
      "status": "SUCCESS",
      "orderedAt": "2024-11-13T13:46:38.385Z",
      "completedAt": "2024-11-13T13:46:39.638Z",
      "errorMessage": null
    },
    {
      "type": "R65",
      "status": "PENDING",
      "orderedAt": "2024-11-13T13:46:38.392Z",
      "completedAt": null,
      "errorMessage": null
    }
  ]
}

GET /order#

With an orderId, the client can at any time know where the data request(s) stand.

Example response:

{
  "id": "904ae72d-fd16-446c-914f-fd5ff3eca689",
  "status": "SUCCESS",
  "requests": [
    {
      "type": "C68",
      "status": "SUCCESS",
      "orderedAt": "2024-01-01T10:20:30Z",
      "completedAt": "2024-01-01T10:20:32Z",
      "dataUrl": "https://....",
      "errorMessage": null
    },
    {
      "type": "R65",
      "status": "SUCCESS",
      "orderedAt": "2024-01-01T10:20:30Z",
      "completedAt": "2024-01-01T10:20:32Z",
      "dataUrl": "https://...",
      "errorMessage": null
    }
  ]
}

If the dataUrl fields are populated, then the data is available at the indicated address, in JSON format.

Error handling#

Example error:

{
  "id": "...",
  "status": "SOME_REQUESTS_FAILED",
  "requests": [
    {
      "type": "R63",
      "status": "FAILED",
      "orderedAt": "2024-07-29T07:52:19.903Z",
      "completedAt": "2024-07-29T07:53:08.629Z",
      "dataUrl": null,
      "errorMessage": "La demande ne peut aboutir : aucun service souscrit de courbe de charge n'est present pour la periode demandee"
    }
  ]
}

{
  "consentId": "47608cf7-1396-47fa-ada0-087de727b291",
  "requests": [
    {
      "type": "LOADCURVE",
      "direction": "CONSUMPTION",
      "enedisRetryAfterLoadcurveActivation": true
    }
  ]
}

GET /request/{requestId}/data#

Retrieve LOADCURVE data

CSV Format#

The returned data is in UTC time, and "starting step".

startDate,powerInWatts
2024-12-15T23:00:00.000Z,321
2024-12-15T23:10:00.000Z,294

JSON Format#

{
  "period": "PT600S",
  "startsAt": "2024-12-15T23:00:00.000Z",
  "endsAt": "2024-12-16T23:00:00.000Z",
  "values": [321, 294]
}

GET /ask#

List existing Asks.

You can filter by the following fields: status, prm.

For more details, see the API specification.

Important points#

What Switchgrid handles#

• Automatic verification of the correspondence between the PRM/PDL number and the name provided when collecting consent.
• Exchanges with Enedis during random regulatory controls.

What Switchgrid does not handle#

• PRMs that are not within Enedis' scope (cities with local historical DSOs like Strasbourg or Grenoble)
• PRMs without smart meters
• Identity verification of the person filling out the consent form
• In case the authorized person is not the contract holder: ensuring that the authorized person is actually authorized.

Webhooks#

Webhooks allow you to receive notifications, for example when an Ask is signed, or when an Order has new data available.

General format#

Webhooks are HTTP POST requests sent to the address you define in your dashboard.

{
    "event": {
        "_tag": "order.request_success",
        "createdAt": "2024-09-17T10:21:32.262Z",
        "organizationId": "a0efdd19-de68-480d-a92f-458ffd98f5c2",
        "orderId": "f720e25e-c662-402e-bd64-aa0771aa819f",
        "requestType": "R63",
        "requestId": "de36dc27-ca90-4c10-ba6c-9524b1f9bcdf"
    }
}

Properties by event tag#