> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engrate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Supplier Switches

> List the supplier switches of your organization, oldest first.

Each switch shows its state, the data you declared, and each request that Engrate made to the market. Every filter you give must match. Engrate reads `state` as of today on the calendar of the market: an accepted switch is `accepted` before its effective date and `effected` from that date.

Errors:

- `404`: your organization is not set up for market communication. Contact   Engrate.

- `422`: a filter is not valid. For example, `state` is not a switch state.



## OpenAPI

````yaml /openapi.json get /market-access/v1alpha1/supplier-switches
openapi: 3.1.0
info:
  title: Engrate API
  version: 1.0.0
servers:
  - url: https://api.engrate.io
security:
  - apiKeyAuth: []
paths:
  /market-access/v1alpha1/supplier-switches:
    get:
      tags:
        - structuring
      summary: List Supplier Switches
      description: >-
        List the supplier switches of your organization, oldest first.


        Each switch shows its state, the data you declared, and each request
        that Engrate made to the market. Every filter you give must match.
        Engrate reads `state` as of today on the calendar of the market: an
        accepted switch is `accepted` before its effective date and `effected`
        from that date.


        Errors:


        - `404`: your organization is not set up for market communication.
        Contact   Engrate.


        - `422`: a filter is not valid. For example, `state` is not a switch
        state.
      operationId: list_supplier_switches_market_access_v1alpha1_supplier_switches_get
      parameters:
        - description: Only the supplier switch with this identifier.
          in: query
          name: id
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            description: Only the supplier switch with this identifier.
            title: Id
        - description: Only switches of the accounting point with this Engrate identifier.
          in: query
          name: accounting_point_id
          required: false
          schema:
            anyOf:
              - format: uuid
                type: string
              - type: 'null'
            description: >-
              Only switches of the accounting point with this Engrate
              identifier.
            title: Accounting Point Id
        - description: Only switches in this market.
          in: query
          name: market
          required: false
          schema:
            anyOf:
              - const: DE
                type: string
              - type: 'null'
            description: Only switches in this market.
            title: Market
        - description: >-
            Only switches of the accounting point with this market identifier.
            In Germany, the MaLo-ID.
          in: query
          name: accounting_point_market_identifier
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Only switches of the accounting point with this market identifier.
              In Germany, the MaLo-ID.
            examples:
              - '26611699793'
            title: Accounting Point Market Identifier
        - description: Only switches in this state.
          in: query
          name: state
          required: false
          schema:
            anyOf:
              - enum:
                  - pending
                  - requested
                  - accepted
                  - effected
                  - rejected
                  - cancelled
                  - superseded
                type: string
              - type: 'null'
            description: Only switches in this state.
            title: State
        - description: Only switches with an effective date on or after this date.
          in: query
          name: effective_date_from
          required: false
          schema:
            anyOf:
              - format: date
                type: string
              - type: 'null'
            description: Only switches with an effective date on or after this date.
            title: Effective Date From
        - description: Only switches with an effective date on or before this date.
          in: query
          name: effective_date_to
          required: false
          schema:
            anyOf:
              - format: date
                type: string
              - type: 'null'
            description: Only switches with an effective date on or before this date.
            title: Effective Date To
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplierSwitchList'
          description: Successful Response
        '404':
          description: >-
            Your organization is not set up for market communication. Contact
            Engrate.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
components:
  schemas:
    SupplierSwitchList:
      properties:
        items:
          description: The supplier switches that match the filters, oldest first.
          items:
            discriminator:
              mapping:
                DE: '#/components/schemas/DeSupplierSwitch'
              propertyName: market
            oneOf:
              - $ref: '#/components/schemas/DeSupplierSwitch'
          title: Items
          type: array
      required:
        - items
      title: SupplierSwitchList
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    DeSupplierSwitch:
      description: A supplier switch for a German accounting point.
      properties:
        accounting_point_id:
          description: The Engrate identifier of the accounting point.
          format: uuid
          title: Accounting Point Id
          type: string
        accounting_point_market_identifier:
          description: >-
            The identifier that the market gives to the accounting point. In
            Germany, the 11-digit market location ID (MaLo-ID).
          examples:
            - '26611699793'
          title: Accounting Point Market Identifier
          type: string
        created_at:
          description: When Engrate accepted the structure batch that created the switch.
          format: date-time
          title: Created At
          type: string
        declared:
          description: The data you gave when you created the switch.
          discriminator:
            mapping:
              consumption: '#/components/schemas/DeConsumptionDeclared'
              production: '#/components/schemas/DeProductionDeclared'
            propertyName: accounting_point_type
          oneOf:
            - $ref: '#/components/schemas/DeConsumptionDeclared'
            - $ref: '#/components/schemas/DeProductionDeclared'
          title: Declared
        effective_date:
          description: >-
            The date from which you asked to supply the accounting point. Supply
            starts on this date only if the market accepts the switch.
          format: date
          title: Effective Date
          type: string
        id:
          description: The identifier of the supplier switch.
          format: uuid
          title: Id
          type: string
        market:
          const: DE
          description: The market of the accounting point.
          title: Market
          type: string
        requests:
          description: >-
            The requests that Engrate made to the grid operator, oldest first.
            Empty until Engrate makes the first request. The `delivery_status`
            of each request shows where its message is on its way to the market.
          items:
            $ref: '#/components/schemas/DeSwitchRequest'
          title: Requests
          type: array
        state:
          description: >-
            Where the switch stands today, on the calendar of the market. See
            [Supplier
            switches](/market-communication/structuring/supplier-switches#follow-a-switch).
          discriminator:
            mapping:
              accepted: '#/components/schemas/AcceptedState'
              cancelled: '#/components/schemas/CancelledState'
              effected: '#/components/schemas/EffectedState'
              pending: '#/components/schemas/PendingState'
              rejected: '#/components/schemas/RejectedState'
              requested: '#/components/schemas/RequestedState'
              superseded: '#/components/schemas/SupersededState'
            propertyName: kind
          oneOf:
            - $ref: '#/components/schemas/PendingState'
            - $ref: '#/components/schemas/RequestedState'
            - $ref: '#/components/schemas/AcceptedState'
            - $ref: '#/components/schemas/EffectedState'
            - $ref: '#/components/schemas/RejectedState'
            - $ref: '#/components/schemas/CancelledState'
            - $ref: '#/components/schemas/SupersededState'
          title: State
        state_updated_at:
          description: >-
            When Engrate last recorded a change of state. An accepted switch
            becomes `effected` on its effective date without a new record, so
            this time does not change then.
          format: date-time
          title: State Updated At
          type: string
      required:
        - accounting_point_id
        - accounting_point_market_identifier
        - created_at
        - declared
        - effective_date
        - id
        - market
        - requests
        - state
        - state_updated_at
      title: DeSupplierSwitch
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    DeConsumptionDeclared:
      description: What you declared for a German accounting point that consumes energy.
      properties:
        accounting_point_type:
          const: consumption
          description: The accounting point consumes energy.
          title: Accounting Point Type
          type: string
        balance_group:
          $ref: '#/components/schemas/ExtraIdentifier'
          description: The balance group that you supply the accounting point in.
        customer:
          $ref: '#/components/schemas/DeSwitchCustomer'
        enfg_eligibility:
          description: >-
            Whether the customer qualifies for reduced levies under the Energy
            Financing Act (Energiefinanzierungsgesetz, EnFG) at this accounting
            point. Required for a consumption accounting point.
          discriminator:
            mapping:
              customer_does_not_qualify: '#/components/schemas/DeEnfgCustomerDoesNotQualify'
              customer_qualifies: '#/components/schemas/DeEnfgCustomerQualifies'
              location_does_not_qualify: '#/components/schemas/DeEnfgLocationDoesNotQualify'
            propertyName: kind
          oneOf:
            - $ref: '#/components/schemas/DeEnfgCustomerQualifies'
            - $ref: '#/components/schemas/DeEnfgCustomerDoesNotQualify'
            - $ref: '#/components/schemas/DeEnfgLocationDoesNotQualify'
          title: Enfg Eligibility
        grid_operator:
          $ref: '#/components/schemas/ExtraIdentifier'
          description: The grid operator that Engrate sends the request to.
          examples:
            - kind: de.bdew
              value: '9903123000007'
      required:
        - accounting_point_type
        - balance_group
        - customer
        - enfg_eligibility
        - grid_operator
      title: DeConsumptionDeclared
      type: object
    DeProductionDeclared:
      description: What you declared for a German accounting point that produces energy.
      properties:
        accounting_point_type:
          const: production
          description: The accounting point produces energy.
          title: Accounting Point Type
          type: string
        balance_group:
          $ref: '#/components/schemas/ExtraIdentifier'
          description: The balance group that you supply the accounting point in.
        customer:
          $ref: '#/components/schemas/DeSwitchCustomer'
        grid_operator:
          $ref: '#/components/schemas/ExtraIdentifier'
          description: The grid operator that Engrate sends the request to.
          examples:
            - kind: de.bdew
              value: '9903123000007'
      required:
        - accounting_point_type
        - balance_group
        - customer
        - grid_operator
      title: DeProductionDeclared
      type: object
    DeSwitchRequest:
      description: >-
        One request that Engrate made to the grid operator for the switch, and
        how it ended.
      properties:
        market_message:
          $ref: '#/components/schemas/DeMarketMessage'
        outcome:
          anyOf:
            - discriminator:
                mapping:
                  accepted: '#/components/schemas/RequestAccepted'
                  failed: '#/components/schemas/RequestFailed'
                  rejected: '#/components/schemas/RequestRejected'
                propertyName: kind
              oneOf:
                - $ref: '#/components/schemas/RequestAccepted'
                - $ref: '#/components/schemas/RequestRejected'
                - $ref: '#/components/schemas/RequestFailed'
            - type: 'null'
          description: >-
            How the request ended. Null while Engrate waits for the decision of
            the market.
          title: Outcome
        requested_at:
          description: When Engrate made the request.
          format: date-time
          title: Requested At
          type: string
      required:
        - market_message
        - requested_at
      title: DeSwitchRequest
      type: object
    AcceptedState:
      description: The market accepted the switch. The effective date is in the future.
      properties:
        kind:
          const: accepted
          title: Kind
          type: string
      required:
        - kind
      title: AcceptedState
      type: object
    CancelledState:
      description: The switch was cancelled before Engrate made a request.
      properties:
        kind:
          const: cancelled
          title: Kind
          type: string
      required:
        - kind
      title: CancelledState
      type: object
    EffectedState:
      description: >-
        The market accepted the switch, and the effective date has come. You
        supply the accounting point.
      properties:
        kind:
          const: effected
          title: Kind
          type: string
      required:
        - kind
      title: EffectedState
      type: object
    PendingState:
      description: >-
        Engrate has not made a request to the market, or the last request
        failed.
      properties:
        block:
          anyOf:
            - $ref: '#/components/schemas/SwitchBlock'
            - type: 'null'
          description: Why Engrate does not send a request. Null when nothing stops it.
        kind:
          const: pending
          title: Kind
          type: string
      required:
        - kind
      title: PendingState
      type: object
    RejectedState:
      description: The market rejected the switch.
      properties:
        kind:
          const: rejected
          title: Kind
          type: string
        market_reason:
          $ref: '#/components/schemas/MarketReason'
          description: Why the market rejected the switch.
      required:
        - kind
        - market_reason
      title: RejectedState
      type: object
    RequestedState:
      description: >-
        Engrate made a request and waits for the decision of the market. The
        `delivery_status` of the request shows where its message is on its way
        to the market.
      properties:
        kind:
          const: requested
          title: Kind
          type: string
      required:
        - kind
      title: RequestedState
      type: object
    SupersededState:
      description: The market ended the switch before it took effect.
      properties:
        kind:
          const: superseded
          title: Kind
          type: string
      required:
        - kind
      title: SupersededState
      type: object
    ExtraIdentifier:
      description: >-
        A code that an external registry or authority gives to a party or an
        area, together with its kind.
      example:
        kind: eic
        value: 46X000000000245K
      properties:
        kind:
          $ref: '#/components/schemas/IdentifierKind'
          description: The kind of identifier
        value:
          description: The identifier value
          title: Value
          type: string
      required:
        - kind
        - value
      title: ExtraIdentifier
      type: object
    DeSwitchCustomer:
      additionalProperties: false
      description: >-
        The customer at the accounting point, as the grid operator knows it.
        Engrate sends these values in the request.
      properties:
        city:
          description: The city of the customer address.
          title: City
          type: string
        country_code:
          description: The country of the customer address, as an ISO 3166-1 alpha-2 code.
          examples:
            - DE
          title: Country Code
          type: string
        house_number:
          description: The house number of the customer address.
          title: House Number
          type: string
        name:
          description: The name of the customer.
          title: Name
          type: string
        postcode:
          description: The postcode of the customer address.
          title: Postcode
          type: string
        street:
          description: The street of the customer address.
          title: Street
          type: string
      required:
        - city
        - country_code
        - house_number
        - name
        - postcode
        - street
      title: DeSwitchCustomer
      type: object
    DeEnfgCustomerDoesNotQualify:
      additionalProperties: false
      description: The customer does not qualify for reduced levies.
      properties:
        kind:
          const: customer_does_not_qualify
          title: Kind
          type: string
      required:
        - kind
      title: DeEnfgCustomerDoesNotQualify
      type: object
    DeEnfgCustomerQualifies:
      additionalProperties: false
      description: >-
        The customer qualifies for reduced levies for the reasons given, and
        Engrate will say so in the registration message to the grid operator.
        The customer must still notify the grid operator itself, as § 52 of the
        Energy Financing Act (Energiefinanzierungsgesetz) requires.
      properties:
        kind:
          const: customer_qualifies
          title: Kind
          type: string
        privilege_reasons:
          description: >-
            The reasons the customer qualifies. Each is a code from [List EnFG
            privilege
            reasons](/api-reference/structuring/list-enfg-privilege-reasons),
            and each code can occur once.
          items:
            $ref: '#/components/schemas/EnfgPrivilegeReasonCode'
          minItems: 1
          title: Privilege Reasons
          type: array
      required:
        - kind
        - privilege_reasons
      title: DeEnfgCustomerQualifies
      type: object
    DeEnfgLocationDoesNotQualify:
      additionalProperties: false
      description: >-
        The accounting point does not qualify for reduced levies, so no
        statement is made about the customer.
      properties:
        kind:
          const: location_does_not_qualify
          title: Kind
          type: string
      required:
        - kind
      title: DeEnfgLocationDoesNotQualify
      type: object
    DeMarketMessage:
      description: The message that carries the request to the market.
      properties:
        delivery_status:
          $ref: '#/components/schemas/DeliveryStatus'
          description: Where the message is on its way to the market.
          examples:
            - delivered
        references:
          $ref: '#/components/schemas/DeSwitchRequestReferences'
      required:
        - delivery_status
        - references
      title: DeMarketMessage
      type: object
    RequestAccepted:
      description: The market accepted the request.
      properties:
        decided_at:
          description: The time the market gives in the message that carries its decision.
          format: date-time
          title: Decided At
          type: string
        kind:
          const: accepted
          title: Kind
          type: string
      required:
        - decided_at
        - kind
      title: RequestAccepted
      type: object
    RequestFailed:
      description: The request ended without a decision of the market.
      properties:
        detail:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            More about the failure. For a failure that the market reports, the
            error code and text of the market. Null when there is no more data.
          title: Detail
        failed_at:
          description: >-
            When the request failed: the time of the market message that reports
            the failure. When no market message reports it, the time Engrate
            detected the failure, or the end of the 10-day wait for a decision.
          format: date-time
          title: Failed At
          type: string
        kind:
          const: failed
          title: Kind
          type: string
        reason:
          $ref: '#/components/schemas/RequestFailureReason'
          description: Why the request failed.
          examples:
            - answer_timeout
      required:
        - failed_at
        - kind
        - reason
      title: RequestFailed
      type: object
    RequestRejected:
      description: The market rejected the request.
      properties:
        decided_at:
          description: The time the market gives in the message that carries its decision.
          format: date-time
          title: Decided At
          type: string
        kind:
          const: rejected
          title: Kind
          type: string
        market_reason:
          $ref: '#/components/schemas/MarketReason'
          description: Why the market rejected the request.
      required:
        - decided_at
        - kind
        - market_reason
      title: RequestRejected
      type: object
    SwitchBlock:
      description: Why Engrate does not send a request for a pending switch.
      properties:
        reason:
          description: >-
            What stops the request, such as a failed last request. Engrate does
            not send a failed request again on its own.
          examples:
            - 'request failed: answer_timeout'
          title: Reason
          type: string
      required:
        - reason
      title: SwitchBlock
      type: object
    MarketReason:
      description: The reason the market gave for its decision, in the market's own words.
      properties:
        code:
          description: >-
            The code of the reason, as the market sends it. For example, `A01`.
            When the market gives a decision without a code, the code is
            `no_answer_code` and `text` holds what the market sent instead.
          examples:
            - A01
          title: Code
          type: string
        text:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The text that the market sends with the code, in the market's
            language. Null when the market sends no text.
          title: Text
      required:
        - code
      title: MarketReason
      type: object
    IdentifierKind:
      description: >-
        The scheme that issued an identifier.


        ### Available identifier kinds


        - **eic** — Energy Identification Code, issued under the ENTSO-E scheme.


        - **vat** — Value added tax registration number.


        - **gln** — Global Location Number, issued by GS1.


        - **de.bdew** — BDEW code number of a German market party.


        - **se.ediel** — Ediel ID of a Swedish market party.


        - **se.mga_code** — Code of a Swedish metering grid area, such as `ABB`.


        - **no.mga_code** — Code of a Norwegian metering grid area.


        - **nl.mga_code** — EAN-18 code of a Dutch metering grid area
        (netgebied).


        - **esett.mga_type** — Type of a metering grid area in the eSett
        imbalance settlement, such as `DISTRIBUTION`.
      enum:
        - eic
        - vat
        - gln
        - de.bdew
        - se.ediel
        - se.mga_code
        - no.mga_code
        - nl.mga_code
        - esett.mga_type
      examples:
        - eic
      title: IdentifierKind
      type: string
    EnfgPrivilegeReasonCode:
      enum:
        - ZU5
        - ZU6
        - ZU7
        - ZU8
        - ZU9
        - ZV0
        - ZV1
        - ZV2
        - ZV3
      examples:
        - ZU5
      title: EnfgPrivilegeReasonCode
      type: string
    DeliveryStatus:
      description: >-
        Where a message is on its way to the market.


        ### Available delivery statuses


        - **queued** — Engrate has not sent the message yet.


        - **sent** — Engrate sent the message and waits for the receipt.


        - **delivered** — The market channel confirmed the receipt.


        - **failed** — The message did not get to the market, or Engrate cannot
        confirm that it did.


        - **suppressed** — Engrate did not send the message, because your
        organization reads the market but does not send to it.
      enum:
        - queued
        - sent
        - delivered
        - failed
        - suppressed
      examples:
        - queued
      title: DeliveryStatus
      type: string
    DeSwitchRequestReferences:
      description: >-
        The EDIFACT references of the request message. The market quotes them in
        its answers, so you can use them to find the request in the records of
        the grid operator.
      properties:
        interchange_control_reference:
          description: The reference of the interchange (UNB) that carries the message.
          title: Interchange Control Reference
          type: string
        message_reference:
          description: The reference of the UTILMD message (UNH).
          title: Message Reference
          type: string
        transaction_reference:
          description: The reference of the transaction (Vorgang) in the message.
          title: Transaction Reference
          type: string
      required:
        - interchange_control_reference
        - message_reference
        - transaction_reference
      title: DeSwitchRequestReferences
      type: object
    RequestFailureReason:
      description: >-
        Why a switch request ended without a decision of the market.


        ### Available request failure reasons


        - **delivery_failed** — The message did not get to the market, or
        Engrate cannot confirm that it did.


        - **answer_timeout** — The market sent no decision in 10 days.


        - **contrl_rejected** — The market could not read the message. German
        market only.


        - **aperak_313** — The market could not process the message. German
        market only.


        - **superseded** — The market ended the switch before it decided.
      enum:
        - delivery_failed
        - answer_timeout
        - contrl_rejected
        - aperak_313
        - superseded
      examples:
        - delivery_failed
      title: RequestFailureReason
      type: string
  securitySchemes:
    apiKeyAuth:
      in: header
      name: Authorization
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.