Spotnana Offices API

openapi: 3.1.0
info:
  title: Air Offices API
  version: v2
  description: APIs to perform search, checkout and book an air pnr
servers:
- url: https://api-ext-sboxmeta.partners.spotnana.com
  description: Sandbox URL
security:
- Bearer: []
tags:
- name: Offices
  description: APIs to create and manage company offices.
paths:
  /v2/companies/{companyId}/legal-entities/{legalEntityId}/offices:
    parameters:
    - name: companyId
      in: path
      description: Identifier for company.
      required: true
      schema:
        type: string
        format: uuid
      example: 4974a66b-7493-4f41-908c-58ba81093947
    - name: legalEntityId
      in: path
      description: Identifier for legal-entity.
      required: true
      schema:
        type: string
        format: uuid
      example: 4974a66b-7493-4f41-908c-58ba81093946
    post:
      tags:
      - Offices
      summary: Create office
      description: This endpoint creates an office.
      operationId: createOffice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOfficeRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    get:
      tags:
      - Offices
      summary: List offices of the legal entity
      description: "This endpoint list offices of given legal entity. If externalId is provided in query param, the office \nhaving the externalId is fetched.\n"
      operationId: listLegalEntityOffices
      parameters:
      - name: externalId
        in: query
        description: External id of the entity.
        required: false
        schema:
          type: string
        example: office-external-id
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrayOfReference'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v2/companies/{companyId}/office-list:
    parameters:
    - name: companyId
      in: path
      description: Identifier for company.
      required: true
      schema:
        type: string
        format: uuid
      example: 4974a66b-7493-4f41-908c-58ba81093947
    post:
      tags:
      - Offices
      summary: List company offices
      operationId: listOfficesV2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListOfficesV2Request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOfficesV2Response'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/companies/{companyId}/legal-entities/{legalEntityId}/offices/{officeId}:
    parameters:
    - name: companyId
      in: path
      description: Identifier for company.
      required: true
      schema:
        type: string
        format: uuid
      example: 4974a66b-7493-4f41-908c-58ba81093947
    - name: legalEntityId
      in: path
      description: Identifier for legal-entity.
      required: true
      schema:
        type: string
        format: uuid
      example: 4974a66b-7493-4f41-908c-58ba81093947
    - name: officeId
      in: path
      description: Identifier for office.
      required: true
      schema:
        type: string
        format: uuid
      example: 4974a66b-7493-4f41-908c-58ba81093947
    get:
      tags:
      - Offices
      summary: Get office
      description: This endpoint gets an office by ID.
      operationId: getOffice
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfficeV2'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Offices
      summary: Update office
      description: This endpoing updates office by ID.
      operationId: updateOffice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfficeV2'
      responses:
        '204':
          description: Updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Offices
      summary: Delete office
      description: This endpoint deletes office by ID.
      operationId: deleteOffice
      parameters:
      - name: detachUsers
        in: query
        description: Whether to remove this entity's reference from associated user entities.
        schema:
          type: boolean
          default: false
      responses:
        '204':
          description: Deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The specified resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    OffsetBasedPaginationResponseParams:
      type: object
      title: PaginationResponseParams
      description: Pagination parameters for response.
      required:
      - totalNumResults
      properties:
        totalNumResults:
          type: integer
          format: int32
          description: Total number of results.
    EntityId:
      type: object
      description: Identifier of an object
      required:
      - id
      properties:
        id:
          type: string
          format: uuid
          example: b93dc51f-12dd-46c7-b7d6-1cb12cd3f5b3
    OfficeSortParams:
      type: object
      title: OfficeSortParams
      description: Sorting related parameters to return sorted list of offices.
      required:
      - sortBy
      - sortOrder
      properties:
        sortBy:
          $ref: '#/components/schemas/OfficeSortBy'
        sortOrder:
          $ref: '#/components/schemas/SortOrder'
    Reference:
      type: object
      title: Reference object containing uuid and name of the entity.
      description: Reference of an entity
      required:
      - id
      properties:
        id:
          type: string
          format: uuid
          example: b93dc51f-12dd-46c7-b7d6-1cb12cd3f5b3
        name:
          type: string
          example: Name
    ListOfficesV2Response:
      type: object
      title: ListOfficesV2Response
      description: Paginated response for office list
      required:
      - offices
      - paginationParams
      properties:
        offices:
          type: array
          description: List of Offices.
          items:
            $ref: '#/components/schemas/OfficeNode'
        paginationParams:
          $ref: '#/components/schemas/OffsetBasedPaginationResponseParams'
    Latlng:
      title: Latlng
      description: Latitude and Longitude for a Location
      type: object
      required:
      - latitude
      - longitude
      properties:
        latitude:
          type: number
          description: Latitude of the Location
          format: double
          example: 77.1025
        longitude:
          type: number
          description: Longitude of the Location
          format: double
          example: 28.7041
    OfficeV2:
      type: object
      title: Office
      description: Office details.
      properties:
        address:
          $ref: '#/components/schemas/PostalAddress'
        id:
          type: string
          format: uuid
        name:
          type: string
          example: Office
        latlng:
          $ref: '#/components/schemas/Latlng'
        externalId:
          type: string
          example: external-id
        taxId:
          type: string
          example: '123232'
    OffsetBasedPaginationRequestParams:
      type: object
      title: OffsetBasedPaginationRequestParams
      description: Pagination parameters for requests.
      properties:
        offset:
          type: integer
          format: int32
          description: The starting index in the list from which results are returned. The value must be greater than or equal to 0.
          default: 0
          minimum: 0
        limit:
          type: integer
          format: int32
          description: Maximum number of results to be fetched.
          minimum: 1
          default: 100
    OfficeNode:
      type: object
      title: OfficeNode
      description: Info for an office
      required:
      - legalEntityRef
      - office
      properties:
        legalEntityRef:
          $ref: '#/components/schemas/Reference'
        office:
          $ref: '#/components/schemas/OfficeV2'
    ErrorResponse:
      type: object
      properties:
        debugIdentifier:
          type: string
          description: Link to debug the error internally.
        errorMessages:
          type: array
          items:
            type: object
            properties:
              errorCode:
                type: string
                description: Error code to identify the specific errors.
              message:
                type: string
                description: Message containing details of error.
              errorParameters:
                type: array
                description: Error message parameters.
                items:
                  $ref: '#/components/schemas/ErrorParameter'
              errorDetail:
                type: string
                description: More details about the error.
    SortOrder:
      type: string
      description: Sorting order.
      enum:
      - DESC
      - ASC
      example: DESC
      default: ASC
    OfficeSortBy:
      type: string
      title: OfficeSortBy
      description: The field name to sort on.
      enum:
      - NAME
      - LEGAL_ENTITY_NAME
      - COUNTRY_CODE
      - TAX_ID
    ListOfficeFilter:
      type: object
      title: ListOfficeFilter
      description: Filter parameters for list office API.
      properties:
        countries:
          type: array
          items:
            type: string
          description: List of country codes to filter on.
          example:
          - US
          - IN
        officeIds:
          type: array
          items:
            type: string
            format: uuid
          description: List of office ids.
        externalIds:
          type: array
          items:
            type: string
          description: List of external ids.
        legalEntityIds:
          type: array
          items:
            type: string
            format: uuid
          description: List of legal entity ids.
    PostalAddress:
      title: PostalAddress
      description: Postal Address Details
      type: object
      required:
      - addressLines
      - regionCode
      properties:
        addressLines:
          description: Address lines
          type: array
          items:
            type: string
            example: Golden Gate Bridge
        administrativeArea:
          type: string
          description: 'Code of administrative area. For example: DL for Delhi, India.

            Highest administrative subdivision which is used for postal

            addresses of a country or region.

            For example, this can be a state, a province, an oblast, or a prefecture.

            Specifically, for Spain this is the province and not the autonomous

            community (e.g. "Barcelona" and not "Catalonia").

            Many countries don''t use an administrative area in postal addresses. E.g.

            in Switzerland this should be left unpopulated.

            '
          example: CA
        administrativeAreaName:
          type: string
          description: "Name of administrative area. This is full name corresponding to administrativeArea. \nLike Delhi for DL area code. For some places, code and name maybe same as well like Tokyo.\n"
          example: California
        description:
          description: Address description
          type: string
          example: San Francisco Home
        isDefault:
          description: Whether this address is default address in case multiple addresses are specified.
          type: boolean
          example: true
        languageCode:
          description: "BCP-47 language code of the contents of this address (if known). This is often the UI \nlanguage of the input form or is expected to match one of the languages used in the \naddress' country/region, or their transliterated equivalents.\nThis can affect formatting in certain countries, but is not critical to the correctness \nof the data and will never affect any validation or other non-formatting related operations.\nExamples: \"zh-Hant\", \"ja\", \"ja-Latn\", \"en\".\n"
          type: string
          example: en
        locality:
          description: Generally refers to the city/town portion of the address.
          type: string
          example: San Francisco
        locationCode:
          description: IATA 3-letter location code. See https://www.iata.org/en/services/codes.
          type: string
          example: LAX
        organization:
          description: The name of the organization at the address.
          type: string
          example: Spotnana
        postalCode:
          description: Postal code of the address. This is a required field when setting for a user/legal entity/company etc.
          type: string
          example: '94130'
        continentCode:
          description: 2 letter continent code of the continent this address falls in.
          type: string
          example: AF
        recipients:
          description: The recipient at the address.
          type: array
          items:
            type: string
        regionCode:
          description: Region code of the country/region of the address.
          type: string
          example: US
        regionName:
          description: Region name of the country/region of the address.
          type: string
          example: America
        revision:
          type: integer
          format: int32
          example: 1
        sortingCode:
          description: 'Additional, country-specific, sorting code. This is not used

            in most regions. Where it is used, the value is either a string like

            "CEDEX", optionally followed by a number (e.g. "CEDEX 7"), or just a number

            alone, representing the "sector code" (Jamaica), "delivery area indicator"

            (Malawi) or "post office indicator" (e.g. Côte d''Ivoire).

            '
          type: string
          example: Jamaica
        sublocality:
          description: Sublocality of the address. This can be neighborhoods, boroughs, districts.
          type: string
        timezone:
          description: Time zone of the address.
          type: string
          example: America/Los_Angeles
        coordinates:
          description: Map coordinates of the address.
          $ref: '#/components/schemas/Latlng'
    ErrorParameter:
      type: object
      title: ErrorParameter
      description: Error parameter
      properties:
        name:
          type: string
          description: Parameter name
        value:
          type: string
          description: Parameter value
    ListOfficesV2Request:
      type: object
      title: ListOfficesV2Request
      description: List offices request with query, filters, pagination and sort parameters.
      required:
      - paginationParams
      properties:
        searchText:
          type: string
          description: Search text
        paginationParams:
          description: Pagination information.
          $ref: '#/components/schemas/OffsetBasedPaginationRequestParams'
        sortParams:
          description: Sorting related parameters.
          $ref: '#/components/schemas/OfficeSortParams'
        filters:
          type: array
          description: List of filters. Offices matching with any of filters would be returned.
          items:
            $ref: '#/components/schemas/ListOfficeFilter'
    ArrayOfReference:
      type: object
      properties:
        length:
          type: integer
          format: int32
        elements:
          type: array
          description: List of references containing id and name.
          items:
            $ref: '#/components/schemas/Reference'
        totalNumResults:
          type: integer
          format: int32
          description: Total number of results
    CreateOfficeRequest:
      type: object
      title: Create Office request.
      description: Office details.
      properties:
        address:
          $ref: '#/components/schemas/PostalAddress'
        name:
          type: string
          example: Office name
        latlng:
          $ref: '#/components/schemas/Latlng'
        externalId:
          type: string
          example: external-id
        taxId:
          type: string
          example: '123232'
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer