Gridex API

1. Responsibilities

The integration boundary is deliberate: your application owns presentation and verified customer input; Gridex owns the authoritative electricity-retail business state and downstream processing.

2. Authentication

Use the API key only from your backend. Gridex identifies the correct organization from the credential, so requests do not need internal database identifiers or organization-selection fields.

GRIDEX_API_KEY=gridex_live_xxxxxxxxx

Authorization: Bearer $GRIDEX_API_KEY

3. Website checkout

A production checkout should use Gridex as the source for the offer, price area, quote and legal documents. Submit the customer application only after the customer has accepted the exact published versions shown in the UI.

1. Retrieve published offers with GET /website/public-contracts.
2. Resolve the customer’s Swedish price area with POST /website/energy-area/resolve.
3. Create the authoritative quote with POST /website/quote and validate it before final submission.
4. Retrieve the exact legal bundle with GET /website/legal-bundle and display the required documents.
5. Collect the customer’s explicit acceptance evidence and power of attorney when required.
6. Submit the application with one stable Idempotency-Key.

Submit an application

POST https://app.gridex.se/api/v1/website/customer-applications
Authorization: Bearer $GRIDEX_API_KEY
Idempotency-Key: checkout_01JEXAMPLE000000000000000
Content-Type: application/json

{
  "external_customer_id": "customer_12345",
  "auth_user_id": "4f6d1e3a-1e84-4c3f-97be-03ac98f21916",
  "customer_portal_user_id": "4f6d1e3a-1e84-4c3f-97be-03ac98f21916",
  "offer_reference": "offer_variable_monthly",
  "quote_reference": "quote_01JEXAMPLE000000000000000",
  "price_option_reference": "variable_monthly_standard",
  "invoice_delivery_method": "email",
  "selected_component_references": [],
  "site_count": 1,
  "legal_bundle_version": "2026-08-19",
  "legal_acceptances": [
    {
      "requirement_code": "agreement",
      "document_reference": "legal_customer_document_example",
      "document_version": "3",
      "document_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "accepted": true,
      "accepted_at": "2026-08-19T10:00:00.000Z"
    },
    {
      "requirement_code": "power_of_attorney",
      "document_reference": "legal_customer_document_poa_example",
      "document_version": "2",
      "document_hash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "accepted": true,
      "accepted_at": "2026-08-19T10:00:00.000Z"
    }
  ],
  "customer": {
    "customer_type": "private",
    "first_name": "Anna",
    "last_name": "Andersson",
    "personal_number": "19900101-1234",
    "email": "anna@example.se",
    "phone": "+46701234567"
  },
  "site": {
    "street": "Example Street 1",
    "postal_code": "11122",
    "city": "Stockholm",
    "country": "SE",
    "annual_consumption_kwh": 4500
  },
  "powerOfAttorney": {
    "accepted": true,
    "scope": ["supplier_switch", "facility_information_lookup"],
    "signerName": "Anna Andersson",
    "signerIdentityNumber": "19900101-1234",
    "method": "website_acceptance",
    "acceptedAt": "2026-08-19T10:00:00.000Z",
    "textVersionId": "00000000-0000-4000-8000-000000000001",
    "ipAddress": "192.0.2.10",
    "userAgent": "<customer browser user agent>"
  }
}

For automated power-of-attorney email, record the customer’s IP at acceptance and send it as powerOfAttorney.ipAddress from your trusted backend, with the original acceptedAt. Gridex creates a stable verification number and archives the accepted text, scopes and evidence as a PDF, with the verification number on every page. The IP of your API server is recorded separately. A form click or method: bankid does not prove a verified BankID signature. BankID is optional; missing evidence blocks external email until completed. Organization users can retrieve their PDFs in OPS under Fullmakter; platform administrators can search across organizations.

The legal references, hashes and versions in this example are placeholders. In production, copy the exact values returned by the legal-bundle endpoint. Do not generate or modify them locally.

Successful checkout response

The immediate customer-facing checkout result is returned in data.checkout. Use that object for the post-submit UI instead of deriving success from internal processing states.

{
  "data": {
    "application_number": "APP-2026-000123",
    "customer_number": "DX-100123",
    "contract_number": "AVT-100123",
    "contract_status": "signed",
    "signed_at": "2026-08-19T10:00:01.000Z",
    "checkout": {
      "outcome": "agreement_signed",
      "thank_you_ready": true,
      "page_state": "success",
      "customer_action_required": false,
      "application": {
        "application_number": "APP-2026-000123",
        "status": "accepted"
      },
      "agreement": {
        "status": "signed",
        "contract_number": "AVT-100123",
        "signed_at": "2026-08-19T10:00:01.000Z",
        "withdrawal_deadline_at": "2026-09-02T21:59:59.999999Z",
        "signature_snapshot_sha256": "<sha256>"
      },
      "confirmation_email": {
        "expected": true,
        "status": "pending"
      },
      "status_path": "/api/v1/website/customer-applications/APP-2026-000123"
    }
  },
  "request_id": "1eb19095-9fab-4c38-b6db-d28bd0e924d9",
  "contract_schema_version": "2026-10-09.1"
}

These illustrative timestamps show the deadline rule for newly signed qualifying private distance agreements: the end of the fourteenth calendar day after acceptance in Europe/Stockholm. Use the stored deadline returned by Gridex. Previously frozen agreements retain their recorded deadline; confirmation delivery does not change it.

4. Status and lifecycle

Store application_number after a successful submission. Use the application status endpoint after redirects, page refreshes and later visits. It returns the authoritative customer-facing state of the agreement and downstream processing.

GET https://app.gridex.se/api/v1/website/customer-applications/APP-2026-000123
Authorization: Bearer $GRIDEX_API_KEY

{
  "data": {
    "application_number": "APP-2026-000123",
    "status": "processing",
    "contract_number": "AVT-100123",
    "contract_status": "signed",
    "signed_at": "2026-08-19T10:00:01.000Z",
    "communication": {
      "pending": false,
      "sent": [
        { "event_type": "contract.confirmation_sent", "status": "delivered" }
      ]
    },
    "checkout": {
      "thank_you_ready": true,
      "page_state": "success",
      "confirmation_email": { "expected": true, "status": "delivered" }
    }
  },
  "request_id": "1eb19095-9fab-4c38-b6db-d28bd0e924d9",
  "contract_schema_version": "2026-10-09.1"
}

Agreement state and message-delivery state are separate. A confirmation email can still be queued while the agreement is already validly signed. Treat the documented delivery status as authoritative instead of assuming that an email was delivered because the agreement succeeded.

5. Customer Portal API

The Customer Portal API exposes only data belonging to the verified linked customer identity. Use granular scopes and request only the capabilities your portal needs. Available resources include profile data, contracts, sites, invoices, metering values, documents, legal acceptances, powers of attorney, events and notifications.

For customer sync, authenticated_user_reference is the authenticated account subject from your organization's login system. It must resolve an already linked active account in the API credential's organization. An unlinked, disabled or other-organization subject does not grant access or create a link.

Support cases and attachments

Your support page can open cases, exchange messages and attach files with the explicit customer_support.read and customer_support.write scopes. Your staff handle the same cases in OPS, including cases that continue over the phone. Only customer-visible messages and released files are returned; internal notes and staff-only files never are. Upload a file as the raw request body (application/pdf, image/png or image/jpeg, at most 4 MB) with an Idempotency-Key. Every file is quarantined and released only after a content check; rejected files return 422 attachment_rejected and are never served.

Verified customer login (optional)

Your organization can let Gridex verify the end customer's own login (OPS → Inställningar → Kundinloggning). Your server then forwards the login's signed assertion in x-gridex-customer-assertion: a compact JWS (RS256, PS256 or ES256) with your organization's iss and aud, sub = the linked portal user id, exp at most 15 minutes after iat and a unique jti. In report mode a missing or invalid assertion is only logged; when verification is required the API returns 403 customer_assertion_required or 403 customer_assertion_invalid. Organizations without a configuration are unaffected.

Archived powers of attorney: PDF and verification

The independent additive archive contract always requires a fresh, verified x-gridex-customer-assertion, an active linked customer in the API key's organization, and BOTH customer_power_of_attorney.read AND customer_documents.read. This requirement also applies in report mode; a missing provider configuration or an unverified assertion does not authorize archive access. Keep the API key and assertion on your trusted server and expose an authenticated download through your own portal.

List existing archives with GET /customer/powers-of-attorney/evidence. Discovery status archived_unverified describes metadata only. Use the returned verification reference with GET /customer/powers-of-attorney/evidence/{verificationReference}?format=json to verify the actual original bytes, or format=pdf to download the verified PDF (at most 15 MiB). The optional sha256 query compares your supplied digest; an incorrect digest returns submitted_sha256_matches: false in the JSON response without changing the archive. These GET requests never generate a PDF or create consent. Missing original IP/time evidence remains missing; pdf_signature_validation: not_performed does not claim cryptographic PDF-signature or BankID validation.

Full schemas, limits and error responses: current POA archive OpenAPI or pinned release 2026-10-19.1. Existing Website and Customer Portal contract releases are unchanged.

6. Partner API

The Partner API is a streamlined backend-to-backend interface for integrations that need to create customers, sites and contracts, retrieve operational data or subscribe to contract-status changes. Gridex manages the account configuration and product mapping outside the API; the partner sends business data and uses the public references returned in responses.

Create a contract

POST https://app.gridex.se/api/partner/v1/contract
Authorization: Bearer $GRIDEX_API_KEY
Idempotency-Key: partner_contract_01JEXAMPLE000000000
Content-Type: application/json

{
  "customer": {
    "first_name": "Anna",
    "last_name": "Andersson",
    "soc_id": "19900101-1234",
    "customer_type": "PRIVATE",
    "email": "anna@example.se"
  },
  "site": {
    "address": "Example Street 1",
    "zip_code": "11122",
    "city": "Stockholm",
    "country": "SE",
    "site_electricity_type": "CONSUMPTION"
  },
  "power_of_attorney": {
    "poa_type": "WEB",
    "transaction_type": "SWITCH",
    "file_base64": "<pdf_base64>",
    "file_extension": "pdf"
  }
}

Create a webhook subscription

POST https://app.gridex.se/api/partner/v1/webhook/subscription
Authorization: Bearer $GRIDEX_API_KEY
Idempotency-Key: partner_webhook_01JEXAMPLE000000000
Content-Type: application/json

{
  "webhook_event": "CONTRACT_STATUS_CHANGE",
  "target_url": "https://partner.example.com/webhooks/gridex",
  "notification_email": "integration@example.com",
  "signing_secret": "<at-least-32-random-characters>"
}

7. Webhooks

Webhooks are signed change notifications. Verify the HMAC-SHA256 signature against the raw request body and timestamp, reject stale timestamps, and deduplicate by event or delivery identifier before applying side effects. When you need the latest complete state, use the webhook as a signal and retrieve the corresponding resource from Gridex.

POST https://partner.example.com/webhooks/gridex
X-Gridex-Timestamp: 1787130000
X-Gridex-Signature: sha256=<hmac_sha256>
X-Gridex-Event-ID: event_...
X-Gridex-Delivery-ID: delivery_...
Content-Type: application/json

{
  "event_id": "event_...",
  "event_type": "customer_application.status_changed",
  "created_at": "2026-08-19T10:01:00.000Z",
  "aggregate": {
    "type": "website_customer_application",
    "reference": "APP-2026-000123"
  },
  "data": {
    "application_number": "APP-2026-000123",
    "status": "processing",
    "previous_status": "accepted"
  },
  "contract_schema_version": "2026-10-09.1"
}

A temporary failure in your receiver does not change the underlying Gridex business event. Webhook delivery is retried independently according to the configured delivery policy.

8. Reliability and performance

9. Errors and retries

API errors use one structured envelope. Inspect error.code, error.retryable, error.field and error.blockers rather than parsing human-readable messages. Include request_id when contacting Gridex support about a failed request.

{
  "error": {
    "code": "validation_error",
    "message": "The request could not be validated.",
    "retryable": false,
    "field": "customer.email",
    "blockers": []
  },
  "request_id": "1eb19095-9fab-4c38-b6db-d28bd0e924d9",
  "correlation_id": "1eb19095-9fab-4c38-b6db-d28bd0e924d9",
  "contract_schema_version": "2026-10-09.1"
}

10. Endpoint reference

This table shows the current integration endpoints. Historical immutable OpenAPI releases and internal diagnostics are intentionally omitted from the human-readable guide.