API reference

User management

User Management API (v2)

Download OpenAPI description

UsersApi.json

UsersApi.yaml

Servers

Staging URL

https://apis.spotnana.com/

Spotnana mock server

https://developer.spotnana.com/_mock/openapi/usersapi/

Users

APIs to onboard and manage users.

Operations

Create user

Request

This endpoint is used to create user profiles in Spotnana. This is typically used by partner companies to onboard user profiles of their customer organizations.

Bodyapplication/jsonrequired

personalInfoobject(UserPersonalInfo)required

User details.

personalInfo.addressesArray of objects(PostalAddress)

personalInfo.dobobject(DateModel)

Date in ISO 8601 standard.

personalInfo.emailstring(email)

Example: "example@email.com"

personalInfo.genderstring(Gender)

Enum"MALE""FEMALE""UNSPECIFIED""UNDISCLOSED"

personalInfo.identityDocsArray of PassportWrapper (object) or ImmigrationDocumentWrapper (object) or RedressNumberWrapper (object) or KnownTravelerNumberWrapper (object) or NationalDocWrapper (object)(IdentityDocument)

List of user identity documents.

Example: [{"passport":{"docId":"PASSPORTID","expiryDate":{"iso8601":"2017-07-21"},"issueCountry":"IN","issuedDate":{"iso8601":"2017-07-21"},"nationalityCountry":"IN","type":"REGULAR"}},{"ktn":{"number":"123456","issueCountry":"US"}}]

personalInfo.nameobject(Name)

Full name containing first, middle, last (family) names, and suffix.

personalInfo.phoneNumbersArray of objects(PhoneNumber)

personalInfo.profilePictureobject(Image)

An image with meta data. Either the data or url property must be supplied to load the image.

personalInfo.nationalitystring

Nationality of user

Example: "Indian"

personalInfo.titlestring(UserTitle)

Enum"TITLE_UNKNOWN""MR""MS""MRS""MX""MASTER""MISS""DR""PROFESSOR""CAPTAIN"

personalInfo.preferredLanguagestring

Language preferred by user.

Example: "en-US"

personalInfo.preferredPronounstring(PreferredPronoun)

Pronoun preferred by user.

Enum"SHE_HER_HERS""HE_HIM_HIS""THEY_THEM_THEIRS"

personalInfo.travelerNameobject(Name)

A name of user that does not contain special characters.

personalInfo.emergencyContactobject(EmergencyContact)

Emergency contact information.

personalInfo.emergencyContactInfoobject(EmergencyContactInfo)Deprecated

Emergency contact information.

businessInfoobject(BusinessInfo)

User business information.

personastring(Persona)required

Persona of the user

Enum"UNKNOWN_PERSONA""EMPLOYEE""GUEST""PERSONAL""RELATIVE""ADHOC"

billingCurrencystring

Preferred billing currency of the user

Example: "INR"

tierstring(Tier)

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

Enum"BASIC""SEAT1A"

externalIdstring

A partner-assigned user identifier. This value must be unique for all travelers within a PNR.

travelPreferencesobject(TravelPreferences)

User's travel preferences

membershipInfoobject(MembershipInfo)

User's travel preferences

notificationPreferencesobject(NotificationPreferences)

Notification preferences of a user for different notification types.

adhocUserInfoobject(AdhocUserInfo)

Basic information related to ad-hoc traveler profile.

rolesArray of objects(RoleConfig)

relativeOfobject(RelativeOf)Deprecated

Link to primary traveler

travelArrangersobject(UserTravelArrangers)Deprecated

Travel arrangers for a user.

curl -i -X POST \
  https://apis.spotnana.com/v2/users \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "personalInfo": {
      "addresses": [
        {
          "addressLines": [
            "Golden Gate Bridge"
          ],
          "administrativeArea": "CA",
          "administrativeAreaName": "California",
          "description": "San Francisco Home",
          "isDefault": true,
          "languageCode": "en",
          "locality": "San Francisco",
          "locationCode": "LAX",
          "organization": "Spotnana",
          "postalCode": "94130",
          "continentCode": "AF",
          "recipients": [
            "string"
          ],
          "regionCode": "US",
          "regionName": "America",
          "revision": 1,
          "sortingCode": "Jamaica",
          "sublocality": "string",
          "timezone": "America/Los_Angeles",
          "coordinates": {
            "latitude": 77.1025,
            "longitude": 28.7041
          }
        }
      ],
      "dob": {
        "iso8601": "2017-07-21"
      },
      "email": "example@email.com",
      "emergencyContactInfo": {
        "address": {
          "addressLines": [
            "Golden Gate Bridge"
          ],
          "administrativeArea": "CA",
          "administrativeAreaName": "California",
          "description": "San Francisco Home",
          "isDefault": true,
          "languageCode": "en",
          "locality": "San Francisco",
          "locationCode": "LAX",
          "organization": "Spotnana",
          "postalCode": "94130",
          "continentCode": "AF",
          "recipients": [
            "string"
          ],
          "regionCode": "US",
          "regionName": "America",
          "revision": 1,
          "sortingCode": "Jamaica",
          "sublocality": "string",
          "timezone": "America/Los_Angeles",
          "coordinates": {
            "latitude": 77.1025,
            "longitude": 28.7041
          }
        },
        "designation": "MANAGER",
        "email": "emergency-contact@email.com",
        "name": {
          "family1": "Gandas",
          "family2": "FamilyTwo",
          "given": "Vichitr",
          "middle": "Kumar",
          "suffix": "SR",
          "preferred": "Don"
        },
        "phoneNumber": {
          "countryCode": 91,
          "countryCodeSource": "FROM_NUMBER_WITH_PLUS_SIGN",
          "extension": "222",
          "isoCountryCode": "IN",
          "italianLeadingZero": true,
          "nationalNumber": 8150,
          "numberOfLeadingZeros": 1,
          "preferredDomesticCarrierCode": "7",
          "rawInput": "77777",
          "type": "MOBILE"
        },
        "userOrgId": {
          "organizationAgencyId": {
            "id": "string"
          },
          "organizationId": {
            "id": "string"
          },
          "userId": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          },
          "tmcInfo": {
            "id": {
              "id": "f49d00fe-1eda-4304-ba79-a980f565281d"
            },
            "primaryServiceProviderTmc": {
              "tmcId": {
                "id": "f49d00fe-1eda-4304-ba79-a980f565281d"
              }
            },
            "secondaryServiceProviderTmcs": [
              {
                "tmcId": {},
                "supplier": "SABRE",
                "travelType": "AIR"
              }
            ],
            "partnerTmcId": {
              "id": "f49d00fe-1eda-4304-ba79-a980f565281d"
            }
          },
          "tmcBasicInfo": {
            "contractingTmc": {
              "id": {
                "id": "f49d00fe-1eda-4304-ba79-a980f565281d"
              },
              "name": "string",
              "logo": {
                "data": "6935813e12584abda0e43d71cd2ea260",
                "dimensions": {},
                "url": "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"
              }
            },
            "bookingTmc": {
              "id": {
                "id": "f49d00fe-1eda-4304-ba79-a980f565281d"
              },
              "name": "string",
              "logo": {
                "data": "6935813e12584abda0e43d71cd2ea260",
                "dimensions": {},
                "url": "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"
              }
            }
          }
        }
      },
      "gender": "FEMALE",
      "identityDocs": [
        {
          "passport": {
            "docId": "PASSPORTID",
            "expiryDate": {
              "iso8601": "2017-07-21"
            },
            "issueCountry": "IN",
            "issuedDate": {
              "iso8601": "2017-07-21"
            },
            "nationalityCountry": "IN",
            "type": "REGULAR"
          }
        },
        {
          "ktn": {
            "number": "123456",
            "issueCountry": "US"
          }
        }
      ],
      "name": {
        "family1": "Gandas",
        "family2": "FamilyTwo",
        "given": "Vichitr",
        "middle": "Kumar",
        "suffix": "SR",
        "preferred": "Don"
      },
      "phoneNumbers": [
        {
          "countryCode": 91,
          "countryCodeSource": "FROM_NUMBER_WITH_PLUS_SIGN",
          "extension": "222",
          "isoCountryCode": "IN",
          "italianLeadingZero": true,
          "nationalNumber": 8150,
          "numberOfLeadingZeros": 1,
          "preferredDomesticCarrierCode": "7",
          "rawInput": "77777",
          "type": "MOBILE"
        }
      ],
      "profilePicture": {
        "data": "6935813e12584abda0e43d71cd2ea260",
        "dimensions": {
          "height": 120,
          "width": 240
        },
        "url": "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"
      },
      "nationality": "Indian",
      "title": "MR",
      "preferredLanguage": "en-US",
      "preferredPronoun": "SHE_HER_HERS",
      "travelerName": {
        "family1": "Gandas",
        "family2": "FamilyTwo",
        "given": "Vichitr",
        "middle": "Kumar",
        "suffix": "SR",
        "preferred": "Don"
      },
      "emergencyContact": {
        "name": "John Smith",
        "email": "emergency-contact@email.com",
        "designation": "MANAGER",
        "relation": "SPOUSE",
        "phoneNumbers": [
          {
            "countryCode": 91,
            "countryCodeSource": "FROM_NUMBER_WITH_PLUS_SIGN",
            "extension": "222",
            "isoCountryCode": "IN",
            "italianLeadingZero": true,
            "nationalNumber": 8150,
            "numberOfLeadingZeros": 1,
            "preferredDomesticCarrierCode": "7",
            "rawInput": "77777",
            "type": "MOBILE"
          }
        ],
        "preferredLanguage": "en-US"
      }
    },
    "businessInfo": {
      "departmentRef": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string"
      },
      "designation": "MANAGER",
      "email": "user@business.com",
      "employeeId": "101",
      "gradeRef": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string"
      },
      "legalEntityRef": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string"
      },
      "managerRef": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string"
      },
      "officeRef": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string"
      },
      "organizationRef": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string"
      },
      "phoneNumbers": [
        {
          "countryCode": 91,
          "countryCodeSource": "FROM_NUMBER_WITH_PLUS_SIGN",
          "extension": "222",
          "isoCountryCode": "IN",
          "italianLeadingZero": true,
          "nationalNumber": 8150,
          "numberOfLeadingZeros": 1,
          "preferredDomesticCarrierCode": "7",
          "rawInput": "77777",
          "type": "MOBILE"
        }
      ],
      "costCenterRef": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string"
      },
      "countryCode": "USA",
      "workerType": "EMPLOYEE",
      "accountingCode": "123",
      "companySpecifiedAttributes": [
        {
          "fixedColumnName": "contingentType",
          "value": "FSTV"
        }
      ],
      "designatedApproverRefs": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "name": "string"
        }
      ],
      "authorizerEmail": "example@email.com"
    },
    "persona": "EMPLOYEE",
    "relativeOf": {
      "userRef": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string"
      },
      "relation": "SPOUSE"
    },
    "billingCurrency": "INR",
    "tier": "SEAT1A",
    "externalId": "string",
    "travelPreferences": {
      "preferences": {
        "airPref": {
          "airlinePrefs": [
            {
              "airlines": [
                "Indigo"
              ],
              "flightType": "DOMESTIC"
            }
          ],
          "alliancePref": {
            "alliances": [
              "STAR_ALLIANCE"
            ]
          },
          "farePref": {
            "fareTypes": [
              "CHANGEABLE"
            ]
          },
          "homeAirport": "NEW YORK",
          "mealPref": {
            "exclMealPrefs": [
              "VGML"
            ],
            "inclMealPrefs": [
              "VGML"
            ],
            "specialMealDescription": "Veg only meal"
          },
          "numStopPref": {
            "numOfStops": 34
          },
          "seatAmenityPref": {
            "seatAmenityTypes": [
              "WIFI"
            ]
          },
          "seatLocationPrefs": [
            {
              "cabins": [
                "FIRST"
              ],
              "isBulkHeadPref": false,
              "maxFlightDurationInHours": 3,
              "position": "WINDOW"
            }
          ],
          "preferredAirports": [
            {
              "airportName": "San Francisco International Airport",
              "airportCode": "SFO",
              "label": "HOME"
            }
          ]
        },
        "preferredCurrency": "USD",
        "railCards": [
          {
            "cardNumber": "string",
            "expiryDate": {
              "iso8601": "2017-07-21"
            },
            "name": "Veterans Railcard",
            "spotnanaCode": "VET",
            "vendor": "ATOC"
          }
        ],
        "railPref": {
          "preferredRailStations": [
            {
              "stationName": "Chicago Union Station",
              "stationCode": "CHI",
              "cityName": "Chicago",
              "countryCode": "string",
              "label": "HOME"
            }
          ],
          "seatPreference": {
            "hasAccessibility": false,
            "seatTypes": [
              "NORMAL"
            ],
            "seatLocations": [
              "AISLE"
            ],
            "deckLevels": [
              "UPPER_DECK"
            ],
            "seatDirections": [
              "FORWARD"
            ]
          },
          "travelClasses": [
            "FIRST"
          ],
          "coachPreferences": [
            "NON_SMOKING"
          ],
          "conditionalRates": [
            "AAA"
          ]
        },
        "carPref": {
          "vendors": [
            {
              "code": "ZE",
              "name": "HERTZ",
              "isPresentInPreferredVendors": true
            }
          ],
          "carTypes": [
            "ECONOMY"
          ],
          "engineTypes": [
            "PETROL"
          ],
          "transmissionTypes": [
            "AUTOMATIC"
          ],
          "conditionalRates": [
            "AAA"
          ]
        },
        "hotelPref": {
          "hotelParentChains": [
            {
              "chainCode": "EM",
              "chainName": "Mariott"
            }
          ],
          "hotelBrands": [
            {
              "brandCode": "HY",
              "brandName": "Global Hytt Corp."
            }
          ],
          "hotelAmenityTypes": [
            "PARKING"
          ],
          "roomPreference": {
            "isMobilityAccessible": false,
            "bedCount": "ONE_BED",
            "roomType": "SMOKING",
            "mostImportantFact": "BED_COUNT",
            "roomLocation": "HIGH_FLOOR",
            "pillowType": "FOAM",
            "roomAmenityPrefs": [
              "EXTRA_TOWELS"
            ]
          },
          "conditionalRates": [
            "AAA"
          ]
        }
      }
    },
    "membershipInfo": {
      "membershipInfos": [
        {
          "appliedTo": [
            "TAJ"
          ],
          "id": "firstId",
          "issuedBy": "firstIssuedBy",
          "type": "AIR"
        }
      ]
    },
    "notificationPreferences": {
      "preferences": [
        {
          "notificationType": "FLIGHT_NOTIFICATION",
          "emailPreference": {
            "enabled": true,
            "ccEmails": [
              "user@example.com"
            ]
          }
        }
      ]
    },
    "travelArrangers": {
      "travelArrangers": [
        {
          "name": {
            "family1": "Gandas",
            "family2": "FamilyTwo",
            "given": "Vichitr",
            "middle": "Kumar",
            "suffix": "SR",
            "preferred": "Don"
          },
          "email": "example@email.com",
          "phoneNumbers": [
            {
              "countryCode": 91,
              "countryCodeSource": "FROM_NUMBER_WITH_PLUS_SIGN",
              "extension": "222",
              "isoCountryCode": "IN",
              "italianLeadingZero": true,
              "nationalNumber": 8150,
              "numberOfLeadingZeros": 1,
              "preferredDomesticCarrierCode": "7",
              "rawInput": "77777",
              "type": "MOBILE"
            }
          ],
          "userId": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          },
          "status": "PENDING"
        }
      ]
    },
    "adhocUserInfo": {
      "profileOwner": {
        "userId": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        }
      },
      "isSaved": false
    },
    "roles": [
      {
        "roleType": "COMPANY_ADMIN",
        "roleMetadata": {
          "travelArrangerMetadata": {
            "arrangerFor": [
              {
                "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
                "sendConfirmationEmail": false,
                "sendFlightStatsNotificationEmail": false
              }
            ]
          }
        },
        "metadata": {
          "roleType": "TRAVEL_ARRANGER",
          "arrangerFor": [
            {
              "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",
              "sendConfirmationEmail": false,
              "sendFlightStatsNotificationEmail": false
            }
          ]
        }
      }
    ]
  }'

Responses

Created

Bodyapplication/json

idstring(uuid)required

Response

application/json

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Query user

Request

This endpoint queries user of given company based on given identifier like email or external ID. In case includeInactive is true, inactive users are also included in the response.

Query

companyIdstring(uuid)

Identifier for company to search user for. Please specify one of the companyId or tmcId.

Example: companyId=4974a66b-7493-4f41-908c-58ba81093947

tmcIdstring(uuid)

Identifier for TMC to search user for. Please specify one of the companyId or tmcId.

Example: tmcId=b83e9704-2e8e-4256-90bf-2e59c1bcf9f2

emailstring(email)

Email ID of the user.

Example: email=user@example.com

externalIdstring

The partner-assigned user identifier.

Example: externalId=123456

includeInactiveboolean

If true, include inactive users in the response.

Default false

Example: includeInactive=true

curl -i -X GET \
  'https://apis.spotnana.com/v2/users?companyId=4974a66b-7493-4f41-908c-58ba81093947&email=user%40example.com&externalId=123456&includeInactive=true&tmcId=b83e9704-2e8e-4256-90bf-2e59c1bcf9f2' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Bodyapplication/json

lengthinteger(int32)

elementsArray of objects(UserSummary)

List of references containing id and name.

Response

application/json

{
  "length": 0,
  "elements": [
    { … }
  ]
}

List users

Request

List users of a specific TMC or a company.

Bodyapplication/jsonrequired

One of:

List users request

tmcIdobject(EntityId)required

TMC ID

tmcId.idstring(uuid)required

userStatusFilterstring

Retrieve active, inactive, or all users.

Default "ACTIVE"

Enum"ACTIVE""INACTIVE""ALL"

Example: "INACTIVE"

paginationobject(OffsetBasedPaginationRequestParams)required

Pagination parameters for requests.

pagination.offsetinteger(int32)>= 0

The starting index in the list from which results are returned. The value must be greater than or equal to 0.

Default 0

pagination.limitinteger(int32)>= 1

Maximum number of results to be fetched.

Default 100

filtersArray of objects(UserListFilter)

Filters to refine the list of users returned. Users matching with any of the filters would be returned.

sortobject(UserSort)

curl -i -X POST \
  https://apis.spotnana.com/v3/users/list \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "tmcId": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    },
    "userStatusFilter": "INACTIVE",
    "pagination": {
      "offset": 0,
      "limit": 100
    },
    "filters": [
      {
        "legalEntityIds": [
          {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          }
        ],
        "officeIds": [
          {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          }
        ],
        "departmentIds": [
          {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          }
        ],
        "costCenterIds": [
          {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          }
        ],
        "userIds": [
          {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          }
        ],
        "emails": [
          "string"
        ],
        "externalIds": [
          "string"
        ],
        "personas": [
          "EMPLOYEE"
        ],
        "roles": [
          "TRAVEL_ARRANGER"
        ],
        "designations": [
          "string"
        ],
        "tiers": [
          "SEAT1A"
        ]
      }
    ],
    "sort": {
      "sortBy": "NAME",
      "sortOrder": "DESCENDING"
    }
  }'

Responses

Bodyapplication/json

usersArray of objects(UserDetail)

Users matching the filters specified in the request.

paginationobject(OffsetBasedPaginationResponseParams)

Pagination parameters for response.

Response

application/json

{
  "users": [
    { … }
  ],
  "pagination": {
    "totalNumResults": 0
  }
}

User Management API (v2)

Users

Create user

RequestExpand all

Responses

Query user

Request

Responses

List users

RequestExpand all

Responses

Request

Request