API reference
/
User management
/
Users
/
List users

User Management API (v2)

Download OpenAPI description
UsersApi.json
UsersApi.yaml
Languages
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

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

OK

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

OK

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
  }
}

Get user

Request

This endpoint gets user details for user ID.

Path
userIdstring(uuid)required

Identifier for user.

Example: 4974a66b-7493-4f41-908c-58ba81093947
Query
includeInactiveboolean

Include inactive users in the response.

Default false
Example: includeInactive=true
curl -i -X GET \
  'https://apis.spotnana.com/v2/users/4974a66b-7493-4f41-908c-58ba81093947?includeInactive=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
idstring(uuid)
personalInfoobject(UserPersonalInfo)

User details.

businessInfoobject(BusinessInfo)

User business information.

personastring(Persona)

Persona of the user

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

Indicates if traveler is active.

Example: true
tierstring(Tier)

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

Enum"BASIC""SEAT1A"
travelPreferencesobject(TravelPreferences)

User's travel preferences

membershipInfoobject(MembershipInfo)

User's travel preferences

notificationPreferencesobject(NotificationPreferences)

Notification preferences of a user for different notification types.

travelArrangersobject(UserTravelArrangers)

Travel arrangers for a user.

adhocUserInfoobject(AdhocUserInfo)

Basic information related to ad-hoc traveler profile.

externalIdstring

The partner-assigned user identifier.

relativeOfobject(RelativeOf)Deprecated

Link to primary traveler

Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "personalInfo": {
    "addresses": [ … ],
    "dob": { … },
    "email": "example@email.com",
    "emergencyContactInfo": { … },
    "gender": "FEMALE",
    "identityDocs": [ … ],
    "name": { … },
    "phoneNumbers": [ … ],
    "profilePicture": { … },
    "nationality": "Indian",
    "title": "MR",
    "preferredLanguage": "en-US",
    "preferredPronoun": "SHE_HER_HERS",
    "travelerName": { … },
    "emergencyContact": { … }
  },
  "businessInfo": {
    "departmentRef": { … },
    "designation": "MANAGER",
    "email": "user@business.com",
    "employeeId": "101",
    "gradeRef": { … },
    "legalEntityRef": { … },
    "managerRef": { … },
    "officeRef": { … },
    "organizationRef": { … },
    "phoneNumbers": [ … ],
    "costCenterRef": { … },
    "countryCode": "USA",
    "workerType": "EMPLOYEE",
    "accountingCode": "123",
    "companySpecifiedAttributes": [ … ],
    "designatedApproverRefs": [ … ],
    "authorizerEmail": "example@email.com"
  },
  "persona": "EMPLOYEE",
  "isActive": true,
  "tier": "SEAT1A",
  "relativeOf": {
    "userRef": { … },
    "relation": "SPOUSE"
  },
  "travelPreferences": {
    "preferences": { … }
  },
  "membershipInfo": {
    "membershipInfos": [ … ]
  },
  "notificationPreferences": {
    "preferences": [ … ]
  },
  "travelArrangers": {
    "travelArrangers": [ … ]
  },
  "adhocUserInfo": {
    "profileOwner": { … },
    "isSaved": false
  },
  "externalId": "string"
}
Copyright © 2025 Spotnana Technology, Inc.