Spotnana Legal Entities API

openapi: 3.1.0
info:
  title: Air Legal Entities 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: Legal Entities
  description: APIs to create and manage company legal entities.
paths:
  /v2/companies/{companyId}/legal-entities:
    parameters:
    - name: companyId
      in: path
      description: Identifier for company.
      required: true
      schema:
        type: string
        format: uuid
      example: 4974a66b-7493-4f41-908c-58ba81093947
    post:
      tags:
      - Legal Entities
      summary: Create legal entity
      description: This endpoint creates a legal entity.
      operationId: createLegalEntity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LegalEntityCreateRequest'
      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:
      - Legal Entities
      summary: List legal entities
      description: "This endpoint lists legal entities of a company. If externalId is provided in the query param \nonly the legal entity having the provided externalId is returned.\n"
      operationId: listLegalEntities
      parameters:
      - name: pageNumber
        in: query
        description: Page number to fetch for the query. Page number starts from 1.
        required: false
        schema:
          type: integer
          format: int32
          minimum: 1
          default: 1
          example: 2
      - name: pageSize
        in: query
        description: Page size to be to fetch for the query.
        required: false
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 1000
          default: 1000
          example: 20
      - name: externalId
        in: query
        description: External id of the entity.
        required: false
        schema:
          type: string
        example: my-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}/legal-entities/{legalEntityId}:
    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
    get:
      tags:
      - Legal Entities
      summary: Get legal entity
      description: This endpoint gets a legal entity by ID.
      operationId: getLegalEntity
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegalEntity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Legal Entities
      summary: Update legal entity
      description: This endpoint updates a legal entity by ID.
      operationId: updateLegalEntity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LegalEntityUpdateRequest'
      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:
      - Legal Entities
      summary: Delete legal entity
      description: This endpoint deletes a legal entity by ID.
      operationId: deleteLegalEntity
      responses:
        '204':
          description: Deleted
        '400':
          $ref: '#/components/responses/BadRequest'
        '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:
    PersonalCardConfig:
      title: PersonalCardConfig
      description: Configuration for bookings done with Personal card.
      type: object
      properties:
        sendToTraveler:
          type: boolean
          description: A boolean flag to show if expenses are to be sent to traveler's Expense partner account.
          example: false
        personalCardExpenseEmail:
          type: string
          description: The email for the expense partner account.
          example: user@company.com
    ExpensePartnerConfig:
      type: object
      title: ExpensePartnerConfig
      description: Expense Partner Configuration
      required:
      - partner
      properties:
        partner:
          $ref: '#/components/schemas/ExpensePartner'
        emailConfig:
          $ref: '#/components/schemas/EmailConfig'
        travelType:
          type: array
          description: Applicable segments
          items:
            $ref: '#/components/schemas/TravelType'
        isExpensePartnerEnabled:
          type: boolean
          description: A flag denoting is the expense partner config is enabled or not.
          default: true
          example: true
        reportCustomFields:
          type: boolean
          description: Send custom fields to the expense partner if enabled.
          example: true
        personalCardExpenseOwner:
          $ref: '#/components/schemas/ExpenseOwner'
        centralCardExpenseOwner:
          $ref: '#/components/schemas/ExpenseOwner'
        partnerReferralId:
          type: string
          description: Referral id used for this company/legal entity during expense partner setup
          example: 1234hgd
        itineraryConfig:
          $ref: '#/components/schemas/ItineraryConfig'
    EntityId:
      type: object
      description: Identifier of an object
      required:
      - id
      properties:
        id:
          type: string
          format: uuid
          example: b93dc51f-12dd-46c7-b7d6-1cb12cd3f5b3
    ItineraryConfig:
      title: ItineraryConfig
      type: object
      description: Itinerary configuration to control what expenses to send to the partner
      properties:
        skipModificationUpdate:
          type: boolean
          description: Allow modification expenses to be skipped from sending to the partner
          example: true
          default: false
        skipCancellationUpdate:
          type: boolean
          description: Allow cancellation expenses to be skipped from sending to the partner
          example: true
          default: false
    TravelType:
      type: string
      title: TravelType
      description: Travel Type
      enum:
      - AIR
      - HOTEL
      - CAR
      - RAIL
      - LIMO
      - MISC
      - ALL
      example: AIR
    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
    LegalEntityCreateRequest:
      type: object
      required:
      - name
      - billingCurrency
      - address
      properties:
        name:
          type: string
          description: Name of the legal entity
        registeredName:
          type: string
          description: 'The official name of this legal entity as registered with local tax authorities.

            '
        registeredEmail:
          type: string
          description: "The primary email (or alias) used for the \"Registered name\" of this legal entity. \nUsed for official communications, including regulatory, compliance, and invoicing \npurposes.\n"
        address:
          $ref: '#/components/schemas/PostalAddress'
          description: Address of the legal entity.
        billingCurrency:
          type: string
          description: Billing currency for the legal entity.
        dba:
          type: string
          description: Business name, sort form of Doing Business As
        ein:
          type: string
          description: Tax number
        phoneNumbers:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
        isDelayedInvoicingEnabled:
          type: boolean
          description: 'Whether delayed invoicing is enabled for the legal entity. If enabled, travelers of the

            legal entity won''t be charged for trip on checkout, rather the bills would be sent to

            the company later on based on the billing cycle.

            '
        ccEmailAddresses:
          type: array
          description: List of email addresses on which all confirmation emails for this LE will be cc'ed. This is applicable only for company roles 'ORG'
          items:
            type: string
            example: example@gmail.com
        bccEmailAddresses:
          type: array
          description: List of email addresses on which all confirmation emails for this LE will be bcc'ed. This is applicable only for company roles 'ORG'
          items:
            type: string
            example: example@gmail.com
        externalId:
          type: string
          description: External id for legal entity.
          example: legal-entity-external-id
        companySpecifiedAttributes:
          type: array
          items:
            $ref: '#/components/schemas/CompanySpecifiedAttributeLegalEntity'
          description: Company specified attributes or fields for the legal entity.
    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
    ExpensePartner:
      title: Expense Partner
      description: The expense partner name as enum.
      type: string
      enum:
      - EXPENSIFY
      - EMBURSE_CHROMERIVER
      - BREX
      example: EXPENSIFY
    ExpenseOwner:
      type: object
      title: ExpenseOwner
      description: Determines who should the expense be reported against.
      properties:
        traveler:
          type: boolean
          description: Report the expense against the traveler who made the booking. If set to true, central email should not be set.
          example: true
        centralEmail:
          type: string
          description: Report the expense against a central email.
          example: docs@company.com
    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
    LegalEntityUpdateRequest:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the legal entity.
        name:
          type: string
          description: Name of the legal entity
        registeredName:
          type: string
          description: 'The official name of this legal entity as registered with local tax authorities.

            '
        registeredEmail:
          type: string
          description: "The primary email (or alias) used for the \"Registered name\" of this legal entity. \nUsed for official communications, including regulatory, compliance, and invoicing \npurposes.\n"
        address:
          $ref: '#/components/schemas/PostalAddress'
          description: Address of the legal entity.
        billingCurrency:
          type: string
          description: Billing currency for the legal entity.
        dba:
          type: string
          description: Business name, sort form of Doing Business As
        ein:
          type: string
          description: Tax number
        phoneNumbers:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
        isDelayedInvoicingEnabled:
          type: boolean
          description: 'Whether delayed invoicing is enabled for the legal entity. If enabled, travelers of the

            legal entity won''t be charged for trip on checkout, rather the bills would be sent to

            the company later on based on the billing cycle.

            '
        bookingTmcRef:
          $ref: '#/components/schemas/Reference'
          description: Booking TMC of the legal entity.
        expensePartnerConfig:
          $ref: '#/components/schemas/ExpensePartnerConfig'
          description: Configured details of expense partner.
        ccEmailAddresses:
          type: array
          description: List of email addresses on which all confirmation emails will be CCed. This is applicable only for company roles 'ORG'
          items:
            type: string
            example: example@gmail.com
        bccEmailAddresses:
          type: array
          description: List of email addresses on which all confirmation emails will be BCCed. This is applicable only for company roles 'ORG'
          items:
            type: string
            example: example@gmail.com
        externalId:
          description: External id for the legal entity.
          type: string
          example: my-external-id
        companySpecifiedAttributes:
          type: array
          items:
            $ref: '#/components/schemas/CompanySpecifiedAttributeLegalEntity'
          description: Company specified attributes or fields for the legal entity.
    EmailConfig:
      type: object
      title: EmailConfig
      description: The email configuration part of the ExpensePartnerConfig.
      required:
      - expensePartnerEmail
      properties:
        personalCardConfig:
          $ref: '#/components/schemas/PersonalCardConfig'
        centralCardExpenseEmail:
          type: string
          description: Central email for bookings done with central card.
          example: finance+le@company.com
        expensePartnerEmail:
          type: string
          description: The expense partner email where expense receipts are sent to.
          example: receipts@expensify.com
        bccEmail:
          type: string
          description: Email to which we bcc expensify emails
          example: docs@company.com
    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.
    CompanySpecifiedAttributeLegalEntity:
      type: object
      description: Company specified attribute for legal entity.
      required:
      - fieldName
      - value
      properties:
        fieldName:
          type: string
          description: Field name of the attribute
          example: businessId
        value:
          type: string
          description: Field value of the attribute
          example: ABCD
    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
    LegalEntity:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the legal entity.
        name:
          type: string
          description: Name of the legal entity
        registeredName:
          type: string
          description: 'The official name of this legal entity as registered with local tax authorities.

            '
        registeredEmail:
          type: string
          description: "The primary email (or alias) used for the \"Registered name\" of this legal entity. \nUsed for official communications, including regulatory, compliance, and invoicing \npurposes.\n"
        address:
          $ref: '#/components/schemas/PostalAddress'
          description: Address of the legal entity.
        billingCurrency:
          type: string
          description: Billing currency for the legal entity.
        dba:
          type: string
          description: Business name, sort form of Doing Business As
        ein:
          type: string
          description: Tax number
        phoneNumbers:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
        isDelayedInvoicingEnabled:
          type: boolean
          description: 'Whether delayed invoicing is enabled for the legal entity. If enabled, travelers of the

            legal entity won''t be charged for trip on checkout, rather the bills would be sent to

            the company later on based on the billing cycle.

            '
        bookingTmcRef:
          $ref: '#/components/schemas/Reference'
          description: Booking TMC of the legal entity.
        expensePartnerConfig:
          $ref: '#/components/schemas/ExpensePartnerConfig'
          description: Configured details of expense partner.
        ccEmailAddresses:
          type: array
          description: List of email addresses on which all confirmation emails will be CCed. This is applicable only for company roles 'ORG'
          items:
            type: string
            example: example@gmail.com
        bccEmailAddresses:
          type: array
          description: List of email addresses on which all confirmation emails will be BCCed. This is applicable only for company roles 'ORG'
          items:
            type: string
            example: example@gmail.com
        externalId:
          description: External id for the legal entity.
          type: string
          example: my-external-id
        companySpecifiedAttributes:
          type: array
          items:
            $ref: '#/components/schemas/CompanySpecifiedAttributeLegalEntity'
          description: Company specified attributes or fields for the legal entity.
    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
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer