Telenor Sverige Geographic Sites API

openapi: 3.2.0
info:
  title: Management Geographic Sites API
  description: 'The Geographic Sites Management API provides a standardized mechanism

    for managing geographic sites and their details.

    The API consists of a simple set of operations that interact with backend systems in a consistent manner.


    It is assumed that the reader is familiar with software API

    concepts such as REST, JSON and the OpenAPI specification.

    For more information about OpenAPI see OpenAPI Specification.


    ### Response Codes


    This API follows standard response codes defined in the

    HTTP RFC by W3C

    Note that not all 4xx HTTP Status Codes are explicit documented

    in each API-operation such as **401 (UNAUTHORIZED)** and

    **403 (FORBIDDEN)**. These are considered generic ones and clients should be aware

    their presence at all operations.'
  termsOfService: https://www.telenor.se/globalassets/mediabibliotek/telenor-foretag/pdfer/priser-och-villkor/general-terms-and-conditions-october-2012.pdf
  contact:
    name: Telenor Support
    url: https://www.telenor.se/foretag/kundservice/
  version: 4.2.12
servers:
- url: https://apis-test.telenor.se/corporate/geographicSiteManagement
  description: Test environment
tags:
- name: Geographic Sites
  description: Endpoints for managing sites.
paths:
  /corporate/geographicSiteManagement/v1/site/{siteId}:
    put:
      tags:
      - Geographic Sites
      summary: Updates an existing site
      description: Allows to update site details. Not every account is allowed to perform that operation.
      operationId: PUT/v1/site
      parameters:
      - name: siteId
        in: path
        description: The unique identifier of a site.
        required: true
        schema:
          type: string
          description: The unique identifier of a site.
      - name: X-On-Behalf-Of-Org-Nr
        in: header
        description: The organization number when the request is on behalf of another party.
        example: 5564210309
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSiteRequest'
        required: true
      responses:
        '204':
          description: Site updated
        '400':
          description: Invocation failed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
      x-operation-id-source: normalized
      x-operation-id-original: PUT /v1/site
    patch:
      tags:
      - Geographic Sites
      summary: Updates an existing site
      description: Allows to update site details. Not every account is allowed to perform that operation. Implements JSON Patch.
      operationId: PATCH/v1/site
      parameters:
      - name: siteId
        in: path
        description: The unique identifier of a site.
        required: true
        schema:
          type: string
          description: The unique identifier of a site.
      - name: X-On-Behalf-Of-Org-Nr
        in: header
        description: The organization number when the request is on behalf of another party.
        example: 5564210309
      requestBody:
        content:
          application/json:
            schema:
              type: array
              description: The JSON Patch document.
              items:
                $ref: '#/components/schemas/PatchOperation'
        required: true
      responses:
        '204':
          description: Site updated
        '400':
          description: Invocation failed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
      x-operation-id-source: normalized
      x-operation-id-original: PATCH /v1/site
  /corporate/geographicSiteManagement/v2/site:
    post:
      tags:
      - Geographic Sites
      summary: Creates a new site
      operationId: POST/v2/site
      parameters:
      - name: X-On-Behalf-Of-Org-Nr
        in: header
        description: The organization number when the request is on behalf of another party.
        example: 5564210309
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSiteRequestV2'
        required: true
      responses:
        '201':
          description: Site created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSiteResponse'
        '400':
          description: Invocation failed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
      x-operation-id-source: normalized
      x-operation-id-original: POST /v2/site
  /corporate/geographicSiteManagement/v3/sites:
    get:
      tags:
      - Geographic Sites
      summary: Lists the geographical sites for the account
      operationId: GET/v3/sites
      parameters:
      - name: limit
        in: query
        description: The number of items each page should contain.
        required: false
        schema:
          type: integer
          format: int32
        example: 100
      - name: next
        in: query
        description: A continuation token used to fetch the next page when the number of results is larger that the limit
        required: false
        schema:
          type: string
        example: 269444400
      - name: X-On-Behalf-Of-Org-Nr
        in: header
        description: The organization number when the request is on behalf of another party.
        example: 5564210309
      responses:
        '200':
          description: Successful invocation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '400':
          description: Invocation failed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
      x-operation-id-source: normalized
      x-operation-id-original: GET /v3/sites
  /corporate/geographicSiteManagement/v2/site/{siteId}:
    get:
      tags:
      - Geographic Sites
      summary: Retrieves geographical site details for the provided ID
      operationId: GET/v2/site/{siteId}
      parameters:
      - name: siteId
        in: path
        description: The unique identifier of a site.
        required: true
        schema:
          type: string
          description: The unique identifier of a site.
      - name: X-On-Behalf-Of-Org-Nr
        in: header
        description: The organization number when the request is on behalf of another party.
        example: 5564210309
      responses:
        '200':
          description: Successful invocation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiteResponse'
        '400':
          description: Invocation failed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested site does not exist
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The account is not authorized to see the site.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
      x-operation-id-source: normalized
      x-operation-id-original: GET /v2/site/{siteId}
  /corporate/geographicSiteManagement/v1/site/{siteId}/contact:
    get:
      tags:
      - Geographic Sites
      summary: Retrieves all contact details for the given site
      operationId: GET/v1/site/{siteId}/contact
      parameters:
      - name: siteId
        in: path
        description: The unique identifier of a site.
        required: true
        schema:
          type: string
          description: The unique identifier of a site.
      - name: X-On-Behalf-Of-Org-Nr
        in: header
        description: The organization number when the request is on behalf of another party.
        example: 5564210309
      responses:
        '200':
          description: Successful invocation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SafeContact'
        '400':
          description: Invocation failed because of wrong header and/or query parameters
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
      x-operation-id-source: normalized
      x-operation-id-original: GET /v1/site/{siteId}/contact
  /corporate/geographicSiteManagement/v1/site/search:
    get:
      tags:
      - Geographic Sites
      summary: Searches for an existing site by its address
      operationId: GET/v1/site/search
      parameters:
      - name: address
        in: query
        description: The street name.
        required: false
        schema:
          type: string
        example: Storgatan 20
      - name: postalCode
        in: query
        description: The postal code of the address.
        required: false
        schema:
          type: string
        example: 998
      - name: city
        in: query
        description: The city of the address.
        required: false
        schema:
          type: string
        example: Karlskrona
      - name: roomNumber
        in: query
        description: The room number of the address.
        required: false
        schema:
          type: string
        example: 26A
      - name: country
        in: query
        description: The country of the address.
        required: false
        schema:
          type: string
        example: Sweden
      - name: objectId
        in: query
        description: The site's object id.
        required: false
        schema:
          type: string
        example: 123456789
      - name: X-On-Behalf-Of-Org-Nr
        in: header
        description: The organization number when the request is on behalf of another party.
        example: 5564210309
      responses:
        '200':
          description: Site found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSiteResponse'
        '400':
          description: There are many sites matching the provided address.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The site could not be found.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorResponse'
      x-operation-id-source: normalized
      x-operation-id-original: GET /v1/site/search
components:
  schemas:
    UpdateSiteRequest:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AddressRequestV2'
          description: The address given to the site.
        rt90Coordinates:
          $ref: '#/components/schemas/Rt90CoordinatesDto'
          description: RT90 coordinates of the site.
      required:
      - address
    AddressRequestV2:
      type: object
      properties:
        streetName:
          type: string
          description: The street name.
          example: Storgatan
          maxLength: 100
          minLength: 0
        streetNumber:
          type: string
          description: The street number, including any entrance designation letters. Any excessive whitespace, such as between digits and letters, will be trimmed.
          example: 20A
          maxLength: 20
          minLength: 0
        apartmentNumber:
          type: string
          description: The apartment number for the address.
          example: 1102
          maxLength: 20
          minLength: 0
        postalCode:
          type: string
          description: The postal code of the address.
          example: 998
          maxLength: 20
          minLength: 0
        city:
          type: string
          description: The city of the address.
          example: Karlskrona
          maxLength: 40
          minLength: 0
        country:
          type: string
          description: The country of the address in English. Non-English names may be translated.
          example: Sweden
          maxLength: 40
          minLength: 0
      required:
      - city
      - country
      - postalCode
      - streetName
    Rt90CoordinatesDto:
      type: object
      properties:
        rt90X:
          type: integer
          format: int32
          example: 7087271
        rt90Y:
          type: integer
          format: int32
          example: 1719456
      required:
      - rt90X
      - rt90Y
    SafeContact:
      type: object
      properties:
        contactId:
          type: string
          description: The unique identifier of a contact.
          example: C312351
        role:
          type: string
          description: The role of the contact person.
          example: Local Contact
        type:
          type: string
          description: The type of the contact person.
          example: Primary
        firstName:
          type: string
          description: The first name of the contact person.
          example: Jane
        lastName:
          type: string
          description: The last name of the contact person.
          example: Doe
        phone:
          type: string
          description: The phone number of the contact person.
          example: 4550000000
        mobilePhone:
          type: string
          description: The mobile number of the contact person.
          example: 0790000000
        email:
          type: string
          description: The email address of the contact person.
          example: jane.doe@example.se
        roles:
          type: array
          description: The roles of the contact person in their sites.
          items:
            $ref: '#/components/schemas/Role'
    Address:
      type: object
      properties:
        street:
          type: string
          description: The street name.
          example: Storgatan 20
        complement:
          type: string
          description: The complement of the address.
          example: c/o The director
        postalCode:
          type: string
          description: The postal code of the address.
          example: 998
        city:
          type: string
          description: The city of the address.
          example: Karlskrona
        floorNumber:
          type: string
          description: The floor number of the address.
          example: 2
        roomNumber:
          type: string
          description: The room number of the address.
          example: 26A
        country:
          type: string
          description: The country of the address.
          example: Sweden
    JsonNode: {}
    SiteResponse:
      type: object
      properties:
        id:
          type: string
          description: The ID of the site.
          example: 6172314
        objectId:
          type: string
          description: The object ID of the site.
          example: 123456789
        name:
          type: string
          description: The name of the site.
          example: Main office
        role:
          type: string
          description: The role of the site.
          example: Equipment
        address:
          $ref: '#/components/schemas/Address'
          description: The main address of the site.
        coordinates:
          $ref: '#/components/schemas/Rt90CoordinatesDto'
          description: RT90 coordinates of the site.
        status:
          type: string
          description: The status of the site.
          enum:
          - ACTIVE
          - INACTIVE
          - OTHER
        movable:
          type: boolean
          description: Indicates if the site is movable or not. If movable, the site has no address or coordinates.
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: The reason that caused the error.
          example: The provided site does not exist.
        code:
          type: string
          description: An application specific error code to differentiate error responses.
          enum:
          - MISSING_REQUIRED_PARAMETER
          - MISSING_AUTHORIZATION_HEADER
          - MISSING_AGREEMENT_IN_CAS
          - INVALID_INPUT
          - MISSING_ACCOUNT
          - UNAUTHORIZED_HEADER_USAGE
          - URL_NOT_FOUND
          - METHOD_NOT_SUPPORTED
          - NON_EXISTING_SITE
          - NON_EXISTING_CONTACT_ID
          - CONTACT_LINK_FAILURE
          - CONTACT_CREATION_FAILURE
          - UNAUTHORIZED
          - INTERNAL_ERROR
          example: MISSING_REQUIRED_PARAMETER
        timestamp:
          type: integer
          format: int64
          description: The date and time using the epoch standard of when the error occurred.
          example: 1615292025
    CreateSiteContactV2:
      type: object
      properties:
        role:
          type: string
          description: The role of the contact person.
          enum:
          - LOCAL_CONTACT
          - TECHNICAL
          - PLANNED_WORK
          - ALARM_CONTACT
          example: Technical
        firstName:
          type: string
          description: The first name of the contact person.
          example: Jane
          maxLength: 30
          minLength: 0
        lastName:
          type: string
          description: The last name of the contact person.
          example: Doe
          maxLength: 30
          minLength: 0
        email:
          type: string
          format: email
          description: The e-mail name of the contact person.
          example: jane.doe@telenor.se
          maxLength: 320
          minLength: 0
        phoneNumber:
          type: string
          description: 'The phone number of the contact person. If missing the value of ''mobileNumber'' will be used. Phone number should consist only of digits, spaces, dashes with optional leading plus. '
          example: '0455000000'
          maxLength: 20
          minLength: 0
        mobileNumber:
          type: string
          description: 'The mobile number of the contact person. Phone number should consist only of digits, spaces, dashes with optional leading plus. '
          example: '070000000'
          maxLength: 20
          minLength: 0
      required:
      - email
      - firstName
      - mobileNumber
      - role
    PaginatedResultMeta:
      type: object
      properties:
        limit:
          type: integer
          format: int32
          description: The number of results to return.
          example: 100
        next:
          type: string
          description: A continuation token used to fetch the next page when the number of results is larger that the limit
          example: 269444400
        total:
          type: integer
          format: int32
          description: The total number of records found.
          example: 3534
    PatchOperation:
      type: object
      description: The JSON Patch document.
      properties:
        op:
          type: string
          minLength: 1
        path:
          type: string
          minLength: 1
        value:
          $ref: '#/components/schemas/JsonNode'
      required:
      - op
      - path
    Role:
      type: object
      properties:
        role:
          type: string
          description: The role of the contact person in a site.
          example: Local Contact
        type:
          type: string
          description: The type of the contact details in a given site.
          example: Primary
        siteId:
          type: string
          description: The unique identifier of a site.
          example: 453424
    CreateSiteRequestV2:
      type: object
      properties:
        name:
          type: string
          description: A name of the site such as a denoted name of the project site. Will be prefixed with company name.
          example: Projekt Hinsetunneln
          maxLength: 120
          minLength: 0
        externalId:
          type: string
          description: The ID of the site that's generated and stored in a client's system.
          example: 6ffccf49-3fdb-46b2-97ba-fef4ac1a1752
          maxLength: 80
          minLength: 0
        address:
          $ref: '#/components/schemas/AddressRequestV2'
          description: The address given to the site. Required if the site is not movable.
        rt90Coordinates:
          $ref: '#/components/schemas/Rt90CoordinatesDto'
          description: The geographical location of the site expressed in RT 90 Coordinates.
        movable:
          type: boolean
          description: If true, the site is considered movable and address and rt90Coordinates must not be set. Site name is required. Defaults to false
          example: true
        contactPersons:
          type: array
          description: The contact persons related to the site.
          items:
            $ref: '#/components/schemas/CreateSiteContactV2'
          minItems: 1
      required:
      - contactPersons
    CreateSiteResponse:
      type: object
      properties:
        siteId:
          type: string
          description: The ID of the created site.
          example: 620481
    PaginatedResponse:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/PaginatedResultMeta'
        data:
          type: array
          items: {}
x-tagGroups:
- name: API Operations
  tags:
  - Geographic Sites
  - Contact Details
x-provenance:
  method: harvested
  publisher: Telenor Sverige
  source: https://developer.telenor.se/geographic-sites-management/openapi
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)