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

# get a list of sites

> Returns a list of sites corresponding to the search criterias including their offers statuses.

By default, only the ids of the objects are returned.

A complete snaphost of the object can be returned using the view parameter.

Results are paginated.




## OpenAPI

````yaml /api-reference/persons-sites-service-offers.yaml get /sites
openapi: 3.0.3
info:
  title: Person, Site and Service Offer lifecycle
  description: >
    This API manages the lifecycle of persons, sites and service offers as
    described
    [here](https://datanumia.stoplight.io/docs/DatanumiaHome/YXBpOjQ0ODQzMjMy-person-site-and-service-offer-lifecycle)

    Please refer to the following link to get a better understanding of the
    [core
    concepts](https://datanumia.stoplight.io/docs/DatanumiaHome/ZG9jOjM4MDg2NDE5-core-concepts)
    of the Home platform.


    <b>Important notice with regard to those APIs:</b>

    - When subscribing or deleting multiple subscribed offers on a site or
    subscribed offers on multiple sites please provide all sites and subscribe
    offer data in a single POST subscriptions call.

    - They are idempotent. Launching multiple times the same operation will lead
    to the same result

    - They require a complete snapshot of all the objects involved in the
    operation. Those new objects overwrite the existing one. In other words,
    missing properties will be considered empty or null when operations will be
    executed on existing person/site objects
  termsOfService: TODO
  contact:
    email: api@datanumia.com
  version: 2.0.0
servers:
  - url: https://api.home.datanumia.com/api/v2
    description: Production Server
security: []
paths:
  /sites:
    get:
      tags:
        - sites
      summary: get a list of sites
      description: >
        Returns a list of sites corresponding to the search criterias including
        their offers statuses.


        By default, only the ids of the objects are returned.


        A complete snaphost of the object can be returned using the view
        parameter.


        Results are paginated.
      operationId: getMultipleSites
      parameters:
        - name: periodTsOn
          in: query
          description: |
            Define on which element to apply the beginTs and endTs parameters.

            Value can be SITE or SERVICE_OFFER.
          schema:
            type: string
            default: SITE
        - name: page
          in: query
          description: the page to be fetched. Default value is 0
          example: 0
          schema:
            type: integer
        - name: size
          in: query
          description: the page size to be fetched. Default value is 100. Max value is 100
          example: 0
          schema:
            type: integer
            default: 100
            maximum: 100
        - name: beginTs
          in: query
          description: >
            Define the start timestamp of the range to reduce the number of
            sites returned.


            Objects modified within the range are returned.


            This operation relies on the modification date of sites object.


            The supported format is as defined by RFC 3339, section 5.6
            restricted to : full-date'T'partial-time'Z'


            Default is today at midnight -1 days. Period between beginTs and
            endTs is at most 30 days.
          schema:
            type: string
            default: start of previous day at midnight
            format: date-time
          example: '2021-07-21T00:00:00Z'
        - name: endTs
          in: query
          description: >
            Define the end timestamp of the range to reduce the number of sites
            returned.


            Objects modified within the range are returned.


            This operation relies on the modification date of sites object.


            The supported format is as defined by RFC 3339, section 5.6
            restricted to : full-date'T'partial-time'Z'


            Default is today at midnight. Period between beginTs and endTs is at
            most 30 days.
          schema:
            type: string
            default: start of current day at midnight
            format: date-time
          example: '2021-07-22T00:00:00Z'
        - name: serviceOffers
          in: query
          description: >
            The service offers to use as a filter. A service offer code can
            optionaly be defined along with the desired status for the service
            offer.


            Format:  [SERVICE_OFFER_DEF[,SERVICE_OFFER_DEF]]


            SERVICE_OFFER_DEF == <SERVICE_OFFER_CODE>[:STATUS_LIST]


            STATUS_LIST == SERVICE_OFFER_STATUS[;SERVICE_OFFER_STATUS]


            SERVICE_OFFER_STATUS == SUBSCRIPTION_IN_PROGRESS | SUBSCRIBED |
            TERMINATED
          example: OF048:SUBSCRIBED;TERMINATED,OF150
          schema:
            type: string
        - name: view
          in: query
          required: false
          description: >
            By default, the overview mode is delivered, only the ids of the
            objects are returned.

            A complete snaphost of the object can be returned using the details
            parameter.
          schema:
            type: string
            enum:
              - overview
              - details
            default: overview
        - name: siteIds
          in: query
          description: the ids of the sites to fetch
          example: siteId1,siteId2
          schema:
            type: string
        - name: siteCustomerIds
          in: query
          description: the customer ids of the sites to fetch
          example: siteCustomerId1,siteCustomerId2
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SitesList'
        '400':
          description: Functional Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorCode: INVALID_AUTHORIZATION_HEADER_VALUE
                errorDescription: The Authorization header is invalid
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorCode: ACCESS_DENIED
                errorDescription: >-
                  The Authorization token does not have permission to the
                  resource
        '500':
          description: Server error
          content: {}
      security:
        - Bearer:
            - home:referential:sites:read
components:
  schemas:
    SitesList:
      required:
        - page
        - _links
        - _embedded
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/SitesListLinks'
        page:
          $ref: '#/components/schemas/Page'
        _embedded:
          $ref: '#/components/schemas/SitesListEmbedded'
    ErrorResponse:
      required:
        - errorCode
        - errorDescription
      type: object
      properties:
        errorCode:
          description: The error code. Refer to the table bellow
          type: string
        errorDescription:
          type: string
          description: The error description
      description: ErrorResponse
    SitesListLinks:
      required:
        - first
        - prev
        - self
        - next
        - last
      type: object
      properties:
        first:
          $ref: '#/components/schemas/SitesListLinkFirst'
        prev:
          $ref: '#/components/schemas/SitesListLinkPrev'
        self:
          $ref: '#/components/schemas/SitesListLinkSelf'
        next:
          $ref: '#/components/schemas/SitesListLinkNext'
        last:
          $ref: '#/components/schemas/SitesListLinkLast'
    Page:
      required:
        - size
        - totalElements
        - totalPages
        - number
      type: object
      properties:
        totalElements:
          type: integer
          description: number of items in the result
          example: 122
        totalPages:
          type: integer
          description: number of pages in the result
          example: 2
        number:
          type: integer
          description: current page returned
          example: 1
        size:
          type: integer
          description: page size
          example: 100
    SitesListEmbedded:
      required:
        - sites
      type: object
      properties:
        sites:
          type: array
          items:
            $ref: '#/components/schemas/SiteData'
    SitesListLinkFirst:
      required:
        - href
      type: object
      properties:
        href:
          type: string
          example: >-
            https://<DATANUMIA_ROOT_URL>/sites?page=0&beginTs=2021-07-21T00:00:00Z&endTs=2021-07-28T00:00:00Z
    SitesListLinkPrev:
      required:
        - href
      type: object
      properties:
        href:
          type: string
          example: >-
            https://<DATANUMIA_ROOT_URL>/sites?page=0&beginTs=2021-07-21T00:00:00Z&endTs=2021-07-28T00:00:00Z
    SitesListLinkSelf:
      required:
        - href
      type: object
      properties:
        href:
          type: string
          example: >-
            https://<DATANUMIA_ROOT_URL>/sites?page=1&beginTs=2021-07-21T00:00:00Z&endTs=2021-07-28T00:00:00Z
    SitesListLinkNext:
      required:
        - href
      type: object
      properties:
        href:
          type: string
          example: >-
            https://<DATANUMIA_ROOT_URL>/sites?page=1&beginTs=2021-07-21T00:00:00Z&endTs=2021-07-28T00:00:00Z
    SitesListLinkLast:
      required:
        - href
      type: object
      properties:
        href:
          type: string
          example: >-
            https://<DATANUMIA_ROOT_URL>/sites?page=1&beginTs=2021-07-21T00:00:00Z&endTs=2021-07-28T00:00:00Z
    SiteData:
      required:
        - ts
        - ids
      type: object
      properties:
        ts:
          type: string
          description: |
            description: |
              The last modification date of the object as defined by RFC 3339, section 5.6 using the following format: full-date'T'partial-time'Z'
          format: date-time
          example: '2017-07-21T17:32:28Z'
        ids:
          $ref: '#/components/schemas/SiteIds'
        content:
          $ref: '#/components/schemas/GetSiteContentWithServiceOffers'
        _links:
          $ref: '#/components/schemas/SiteLinks'
    SiteIds:
      required:
        - siteId
        - siteCustomerId
      type: object
      properties:
        siteId:
          description: >-
            the id of the site object. It is the id from the Home perspective,
            not the external id one
          type: string
          example: siteId1
          pattern: '[A-Za-z0-9-_]+'
        siteCustomerId:
          type: string
          description: Your site identifier. This id is unique.
          pattern: '[A-Za-z0-9-_]+'
          example: site-45634
    GetSiteContentWithServiceOffers:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/SiteAddressMonitoring'
        pointsOfDelivery:
          $ref: '#/components/schemas/PointsOfDelivery'
        serviceOffers:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ServiceOfferStatuses'
    SiteLinks:
      required:
        - _links
      type: object
      properties:
        self:
          $ref: '#/components/schemas/SiteLinkSelf'
    SiteAddressMonitoring:
      description: Site Address.
      required:
        - zipCode
        - country
      type: object
      properties:
        streetNumberAndName:
          type: string
          example: 4 bis place des vosges
          pattern: ^(.{0,70})$
        streetAdditionalInfo:
          type: string
          example: BP 90137 44701
          pattern: ^(.{0,50})$
        locationAdditionalInfo:
          type: string
          example: Batiment B
          pattern: ^(.{0,40})$
        zipCode:
          type: string
          example: '92400'
          pattern: ^(.{0,20})$
        city:
          type: string
          example: Courbevoie
          pattern: ^(.{0,50})$
        country:
          type: string
          example: France
          pattern: ^(.{0,30})$
    PointsOfDelivery:
      type: object
      properties:
        elec:
          type: array
          minItems: 0
          maxItems: 1
          items:
            $ref: '#/components/schemas/ElecPointOfDelivery'
        gas:
          type: array
          minItems: 0
          maxItems: 1
          items:
            $ref: '#/components/schemas/GasPointOfDelivery'
    ServiceOfferStatuses:
      description: A Home service offer.
      required:
        - code
        - statusHistory
      type: object
      properties:
        code:
          description: The code to use will be given by your CSM contact
          type: string
          example: OF060
        statusHistory:
          description: contains all status changes for a given offer
          type: array
          items:
            $ref: '#/components/schemas/ServiceOfferStatusChange'
    SiteLinkSelf:
      required:
        - href
      type: object
      properties:
        href:
          type: string
          example: https://<DATANUMIA_ROOT_URL>/sites/{site-id}
    ElecPointOfDelivery:
      required:
        - elecPointOfDeliveryId
        - meter
      type: object
      properties:
        elecPointOfDeliveryId:
          type: string
          description: >-
            Identifier of the electricity point of Delivery as managed bu the
            DSO.
          pattern: ^([a-zA-Z0-9_-]{0,50})$
        meter:
          $ref: '#/components/schemas/ElecMeter'
    GasPointOfDelivery:
      description: The required information about the gas meter.
      required:
        - gasPointOfDeliveryId
        - meter
      type: object
      properties:
        gasPointOfDeliveryId:
          type: string
          description: Identifier of the gas measurement point.
        meter:
          $ref: '#/components/schemas/GasPointOfDeliveryParameters'
    ServiceOfferStatusChange:
      type: object
      properties:
        ts:
          description: |
            the timestamp of the status change.
          type: string
          format: date-time
          example: '2021-07-22T00:00:00Z'
        status:
          $ref: '#/components/schemas/ServiceOfferStauts'
    ElecMeter:
      description: The required information about the electrical meter.
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: Electrical meter type.
          enum:
            - ELECTRONIC_METER
            - ELECTROMAGNETIC_METER
            - SMART_METER
            - UNKNOWN
        id:
          type: string
          description: Identifier of the meter from the customer perspective.
          pattern: '[a-zA-Z0-9_-]+'
        firstCommunicationDate:
          type: string
          description: >
            Timestamp of the request as defined by RFC 3339, section 5.6 using
            the following format: full-date
          format: date
          example: '2017-07-21'
          pattern: \d{4}-\d{2}-\d{2}
    GasPointOfDeliveryParameters:
      description: The required information about the gas installation.
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: Gas meter type.
          enum:
            - MECHANICAL_METER
            - SMART_METER
            - UNKNOWN
        digitNumber:
          type: integer
          description: Maximum number of characters in an index reading. 6, by default.
    ServiceOfferStauts:
      type: string
      enum:
        - SUBSCRIPTION_IN_PROGRESS
        - SUBSCRIBED
        - TERMINATED
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer

````