Spotnana Trip Notes API

openapi: 3.1.0
info:
  title: Air Trip Notes 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: Trip Notes
paths:
  /v2/trips/{tripId}/agent-notes:
    parameters:
    - name: tripId
      in: path
      description: Trip Id
      required: true
      schema:
        type: string
        example: '6926658168'
    post:
      tags:
      - Trip Notes
      summary: Create a note for agents
      description: "Creates a note addressed to the agents assigned for a specific trip. \nAgent notes are used to communicate trip-related information to agents handling the trip, \nsuch as special instructions, updates made on the booking, or any unresolved issues reported by the traveler.\n\nUse this endpoint to:\n- Add a note to a trip so the agents working on it will have all the latest information about the trip.\n- Use the optional `pnrId` field in the request body to link a note to a specific PNR within a trip.\n"
      operationId: createAgentNote
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentNoteRequest'
      responses:
        '201':
          description: Created
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    get:
      tags:
      - Trip Notes
      summary: Read all agent notes for a trip
      description: "Retrieves all agent notes associated with a specific trip. \nEach note in the response includes the message, the sender's basic information, \nand timestamps.\n\nUse this endpoint to:\n- Review the full history of agent notes added to a trip.\n- Identify who created each note and when, using the `senderInfo`, `createdAt`, and `updatedAt` fields.\n\n**Note:** The response may contain a `pnrId` if it was added during the note creation. Otherwise, the `pnrId` field is omitted in the response.\n"
      operationId: listAgentNotes
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentNotesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/trips/{tripId}/agent-notes/{noteId}:
    parameters:
    - name: tripId
      in: path
      description: Trip Id
      required: true
      schema:
        type: string
        example: '6926658168'
    - name: noteId
      in: path
      description: Note Id
      required: true
      schema:
        type: string
        example: fc68b68a-ed0a-4aa3-9099-bc7c1211acf1
    delete:
      tags:
      - Trip Notes
      summary: Delete an agent note
      description: "Deletes an existing agent note from a trip. \nOnce deleted, the note cannot be retrieved later.\n\nUse this endpoint to:\n- Remove an agent note that is no longer relevant or was added by mistake.\n"
      operationId: deleteAgentNote
      responses:
        '204':
          description: No Content
        '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'
  schemas:
    TmcBasicInfo:
      type: object
      title: TmcBasicInfo
      description: TMC related basic information.
      required:
      - contractingTmc
      - bookingTmc
      properties:
        contractingTmc:
          $ref: '#/components/schemas/CompanyRef'
          description: Contracting TMC is the TMC the user/organization contracted.
        bookingTmc:
          $ref: '#/components/schemas/CompanyRef'
          description: Booking TMC is the TMC used for the bookings for the user/organization.
    PrimaryServiceProviderTmc:
      type: object
      title: PrimaryServiceProviderTmc
      description: Primary service provider TMC info
      required:
      - tmcId
      properties:
        tmcId:
          $ref: '#/components/schemas/CompanyId'
          description: Id of the service provider TMC.
    SecondaryServiceProviderTmc:
      type: object
      title: SecondaryServiceProviderTmc
      description: Secondary service provider TMC info
      required:
      - tmcId
      - supplier
      - travelType
      properties:
        tmcId:
          $ref: '#/components/schemas/CompanyId'
          description: Id of the service provider TMC.
        supplier:
          $ref: '#/components/schemas/SupplierType'
          description: Supplier for which this service provider should be used.
        travelType:
          $ref: '#/components/schemas/TravelType'
          description: Travel type for which this service provider should be used.
    AgentNote:
      title: AgentNote
      description: Agent Note with details.
      type: object
      required:
      - noteId
      - note
      - senderInfo
      - createdAt
      - updatedAt
      properties:
        noteId:
          $ref: '#/components/schemas/NoteId'
        pnrId:
          type: string
          description: Pnr ID
          example: '6789533589'
        note:
          type: string
          description: Note message
          example: An agent task has been created.
        senderInfo:
          $ref: '#/components/schemas/UserBasicInfo'
        createdAt:
          $ref: '#/components/schemas/DateTimeOffset'
        updatedAt:
          $ref: '#/components/schemas/DateTimeOffset'
    DateTimeOffset:
      title: DateTimeOffset
      description: ISO8601 UTC Date Time
      type: object
      required:
      - iso8601
      properties:
        iso8601:
          type: string
          pattern: ^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-4]):([0-5][0-9])(:([0-5][0-9]))?(Z|([+-](0[0-9]|1[0-4]):([0-5][0-9])))$
          example: 2017-07-21T17:32Z
    Name:
      type: object
      title: Name
      description: Full name containing first, middle, last (family) names, and suffix.
      required:
      - given
      - family1
      properties:
        family1:
          type: string
          description: Last (family) name.
          example: Gandas
          x-pii: SENSITIVE
        family2:
          type: string
          example: FamilyTwo
          x-pii: SENSITIVE
        given:
          type: string
          description: First (given) name.
          example: Vichitr
          x-pii: SENSITIVE
        middle:
          type: string
          description: Middle name.
          example: Kumar
          x-pii: SENSITIVE
        suffix:
          $ref: '#/components/schemas/NameSuffix'
          description: Suffix used with the name. For example SR or JR.
          example: SR
        preferred:
          type: string
          description: Informal preferred name added by traveler. This is not used on any PNR or tickets
          example: Don
          x-pii: SENSITIVE
    TravelType:
      type: string
      title: TravelType
      description: Travel Type
      enum:
      - AIR
      - HOTEL
      - CAR
      - RAIL
      - LIMO
      - MISC
      - ALL
      example: AIR
    TmcInfo:
      type: object
      title: TmcInfo
      description: TMC config information.
      required:
      - id
      - primaryServiceProviderTmc
      properties:
        id:
          $ref: '#/components/schemas/CompanyId'
          description: TMC id.
        primaryServiceProviderTmc:
          $ref: '#/components/schemas/PrimaryServiceProviderTmc'
          description: Primary service provider TMC for the TMC.
        secondaryServiceProviderTmcs:
          type: array
          description: Secondary service provider TMCs for the TMC.
          items:
            $ref: '#/components/schemas/SecondaryServiceProviderTmc'
        partnerTmcId:
          $ref: '#/components/schemas/CompanyId'
          description: Useful to identify the clients onboarded by a PARTNER_TMC
    Image:
      type: object
      title: Image
      description: An image with meta data. Either the `data` or `url` property must be supplied to load the image.
      properties:
        data:
          type: string
          format: byte
          example: 6935813e12584abda0e43d71cd2ea260
        dimensions:
          $ref: '#/components/schemas/Dimensions'
        url:
          type: string
          example: https://static.wixstatic.com/media/73f2e2_6935813e12584abda0e43d71cd2ea260~mv2.png/v1/fill/w_630,h_94,al_c,q_85,usm_0.66_1.00_0.01/Spotnana%403x.webp
    Dimensions:
      type: object
      title: Dimensions
      description: Image dimensions ie width and height.
      properties:
        height:
          type: integer
          format: int32
          example: 120
        width:
          type: integer
          format: int32
          example: 240
    NoteId:
      title: NoteId
      description: Note ID.
      type: object
      required:
      - id
      properties:
        id:
          type: string
          format: uuid
          description: ID
          example: 601e8a5b-3d1d-46bf-9ff6-5441097da8af
    ListAgentNotesResponse:
      title: ListAgentNotesResponse
      description: Response for listing agent notes.
      type: object
      required:
      - agentNotes
      properties:
        agentNotes:
          type: array
          description: Array of agent notes.
          items:
            $ref: '#/components/schemas/AgentNote'
    Persona:
      type: string
      title: Persona
      description: Persona of the user
      enum:
      - UNKNOWN_PERSONA
      - EMPLOYEE
      - GUEST
      - PERSONAL
      - RELATIVE
      - ADHOC
      example: EMPLOYEE
    UserOrgId:
      type: object
      title: UserOrgId
      description: User and user's organization information.
      required:
      - userId
      - organizationId
      properties:
        organizationAgencyId:
          $ref: '#/components/schemas/OrganizationAgencyId'
        organizationId:
          $ref: '#/components/schemas/OrganizationId'
        userId:
          $ref: '#/components/schemas/UserId'
        tmcInfo:
          $ref: '#/components/schemas/TmcInfo'
          deprecated: true
          x-sunset: '2026-07-01'
        tmcBasicInfo:
          $ref: '#/components/schemas/TmcBasicInfo'
    PhoneNumber:
      type: object
      title: PhoneNumber
      description: Properly formatted phone number.
      properties:
        countryCode:
          type: integer
          format: int32
          description: two digit country code
          example: 91
        countryCodeSource:
          type: string
          enum:
          - UNSPECIFIED
          - FROM_NUMBER_WITH_PLUS_SIGN
          - FROM_NUMBER_WITH_IDD
          - FROM_NUMBER_WITHOUT_PLUS_SIGN
          - FROM_DEFAULT_COUNTRY
          example: FROM_NUMBER_WITH_PLUS_SIGN
        extension:
          description: phone number extension
          type: string
          example: '222'
        isoCountryCode:
          description: ISO alpha-2 code
          type: string
          example: IN
        italianLeadingZero:
          type: boolean
          default: false
          example: true
        nationalNumber:
          type: integer
          format: int64
          example: 8150
        numberOfLeadingZeros:
          type: integer
          format: int32
          default: 0
          example: 1
        preferredDomesticCarrierCode:
          type: string
          example: '7'
        rawInput:
          type: string
          example: '77777'
        type:
          type: string
          enum:
          - UNKNOWN_TYPE
          - MOBILE
          - LANDLINE
          example: MOBILE
    CompanyId:
      type: object
      title: CompanyId
      description: Company ID
      required:
      - id
      properties:
        id:
          type: string
          format: uuid
          example: f49d00fe-1eda-4304-ba79-a980f565281d
    UserId:
      type: object
      title: UserId
      description: User identifier
      required:
      - id
      properties:
        id:
          type: string
          format: uuid
    OrganizationId:
      type: object
      title: OrganizationId
      description: Organization id for traveler.
      required:
      - id
      properties:
        id:
          type: string
    CompanyRef:
      type: object
      description: Basic information about a company.
      required:
      - id
      properties:
        id:
          $ref: '#/components/schemas/CompanyId'
        name:
          type: string
        logo:
          $ref: '#/components/schemas/Image'
          description: Company logo
    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.
    SupplierType:
      type: string
      description: Supplier type like Sabre, TravelFusion etc.
      enum:
      - SABRE
      - AMADEUS
      - TRAVEL_FUSION
      - FARELOGIX_NDC
      - ATPCO_NDC
      - TRAINLINE
      - AVIA
      - QBR
      - BCD
      - QANTAS_HOTELS
      - SOUTHWEST
      - EXPEDIA
      - HOTEL_HUB
      - NDC
      - MARRIOTT
      - CLEARTRIP
      - KYTE
      - GROUNDSPAN
      - SABRE_NDC
      - BOOKING_COM
      - CARTRAWLER
      - PREMIER_INN
      - TRAVELODGE
      - ENTERPRISE
      - HYATT
      - NATIONAL
      - ALAMO
      - HERTZ
      - DOLLAR
      - THRIFTY
      - FIREFLY
      - EUROSTAR
      - AVIS
      - BUDGET
      x-ignoreBreakingChanges:
      - SupplierType->PREMIER_INN
      example: SABRE
    Tier:
      type: string
      title: Tier
      description: 'Tier of User.

        Note: In default UI, BASIC is displayed as Standard, and SEAT1A is displayed as VIP.

        '
      enum:
      - BASIC
      - SEAT1A
      x-enum-varnames:
      - BASIC
      - SEAT1A
      example: SEAT1A
      default: BASIC
    ErrorParameter:
      type: object
      title: ErrorParameter
      description: Error parameter
      properties:
        name:
          type: string
          description: Parameter name
        value:
          type: string
          description: Parameter value
    CreateAgentNoteRequest:
      title: CreateAgentNoteRequest
      description: Request for creating a new agent note.
      type: object
      required:
      - note
      properties:
        pnrId:
          type: string
          description: Pnr ID (optional)
          example: '6789533589'
        note:
          type: string
          description: Note message
          example: An agent task has been created.
    NameSuffix:
      title: NameSuffix
      description: Suffix for name
      type: string
      enum:
      - NAME_SUFFIX_UNKNOWN
      - SR
      - JR
      - MD
      - PHD
      - II
      - III
      - IV
      - DO
      - ATTY
      - V
      - VI
      - ESQ
      - DC
      - DDS
      - VM
      - JD
      - SECOND
      - THIRD
      example: SR
    UserBasicInfo:
      type: object
      title: UserBasicInfo
      description: Basic user information.
      properties:
        userOrgId:
          $ref: '#/components/schemas/UserOrgId'
        persona:
          $ref: '#/components/schemas/Persona'
        email:
          type: string
          format: email
          example: example@email.com
          x-pii: IDENTIFIER
        name:
          $ref: '#/components/schemas/Name'
        profilePicture:
          $ref: '#/components/schemas/Image'
        tier:
          $ref: '#/components/schemas/Tier'
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumber'
          x-pii: IDENTIFIER
        employeeId:
          type: string
          description: Employee id of the user
        isActive:
          type: boolean
          description: Whether user profile is active or not.
          example: true
    OrganizationAgencyId:
      type: object
      title: OrganizationAgencyId
      description: Agency id for the organization.
      deprecated: true
      x-sunset: '2026-07-01'
      required:
      - id
      properties:
        id:
          type: string
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer