> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Navan

> Navan (formerly TripActions) is a corporate travel and expense platform; Serval connects to its Booking Data API so workflows can pull travel booking reports on demand.

## About Navan

Navan (formerly TripActions) is a corporate travel and expense platform. The Serval integration connects to the Navan Booking Data API so your workflows can pull your company's travel booking report, including per-booking detail like passengers, pricing, policy compliance, and carbon emissions. The integration ships with one pre-installed workflow, "Get Navan Bookings from Last Week". Serval only ever sends your credentials to one host for this integration: api.navan.com.

**Authentication:** OAuth 2.0 client credentials (Client ID + Client Secret issued from the Navan Admin Dashboard). No user sign-in, no consent screen, no scopes or domain to configure.

**Data sync:** On-demand only. Navan data is read when a workflow step runs - there is no background sync, no webhooks, and no scheduled imports.

## What the Navan integration enables

| Capability                                                | Description                                                                                                                                                                                                                                    |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pull the company booking report                           | Retrieve booking rows with rich detail: passengers, segments, pricing and fees, policy compliance, payment data, carbon emissions, and custom fields.                                                                                          |
| Filter bookings by date and attributes                    | Narrow results by created, updated, or travel dates; by booking status (CANCELED, VOIDED, CONFIRMED, TICKETED, ACCEPTED); by booking type (HOTEL, FLIGHT, CAR, RAIL, TRANSPORTATION, BLACK\_CAR); or by a specific booking or trip identifier. |
| Include per-booking transactions                          | Optionally embed transaction detail (ticket numbers, fees, taxes, totals, coupons) in each booking row.                                                                                                                                        |
| Page through large exports                                | Results are paginated, and responses include page metadata so workflows can walk the full report reliably.                                                                                                                                     |
| Pre-installed workflow: Get Navan Bookings from Last Week | Retrieves all travel bookings created in the last 7 days and returns the complete list with date range information. Runs without approval by default.                                                                                          |

The integration currently models a single resource from the [Navan API](https://app.navan.com/swagger-ui/index.html): the company booking report. Other Navan endpoints are not yet available through Serval.

## Get your credentials

Serval needs a Navan API credential - a Client ID and Secret Key - created from the [Navan Integrations settings](https://app.navan.com/app/admin2/en/settings/integrations). You must have access to the Navan Admin Dashboard to create one.

<Steps>
  <Step title="Open the Navan Admin Dashboard">
    Log in to Navan on the web, click the Navan logo in the top left, and select **Admin** - or go directly to the [Admin Dashboard](https://app.navan.com/app/admin2/en/dashboard).
  </Step>

  <Step title="Go to Integrations settings">
    Navigate to **Travel**, then **Settings**, then **Integrations** in the left menu, or use the [direct link](https://app.navan.com/app/admin2/en/settings/integrations).
  </Step>

  <Step title="Create a new API credential">
    Scroll to the **Navan API Credentials** section and click **Create new**.
  </Step>

  <Step title="Name and create the credential">
    Enter a **Description** (this serves as the credential's name). Optionally restrict it by **Allowed IP Addresses** or **Subnet Mask**. Click **Create**.
  </Step>

  <Step title="Copy the Client ID and Secret Key immediately">
    Copy both values from the confirmation pop-up - use **Copy All** to grab the Description, Client ID, and Secret Key together. Once the pop-up closes, the Secret Key is no longer accessible.
  </Step>
</Steps>

<Warning>
  Navan shows the Secret Key exactly once, in the creation pop-up. If you lose it, use **Rotate Key** on the credential to get a new secret with the same Client ID, then update the Serval connection.
</Warning>

<Note>
  The Description and Client ID cannot be changed after creation. The **Edit** menu on an existing credential supports editing the allowed IP addresses or subnet masks, **Rotate Key** (new secret, same Client ID), and **Revoke**.
</Note>

## Connect in Serval

<Steps>
  <Step title="Open the Navan connection form in Serval">
    Find the Navan integration and start a new connection.
  </Step>

  <Step title="Enter an Instance Name">
    A free-text label for the connection (placeholder: "My Company"). It is used as both the connection's identifier and its display name.
  </Step>

  <Step title="Enter the Client ID">
    Paste the Client ID from your Navan API credential.
  </Step>

  <Step title="Enter the Client Secret">
    Paste the Secret Key from your Navan API credential. After saving, this field displays masked (bullet characters plus the last 4 characters) with a control to replace it.
  </Step>

  <Step title="Submit the form">
    There is no domain and no scopes to configure - Serval always talks to Navan's fixed API host (api.navan.com).
  </Step>
</Steps>

<Warning>
  None of the three fields are marked required, so the form will accept a blank submission. Bad or missing credentials only surface afterward through the connection test - double-check your values before saving.
</Warning>

When editing an existing connection, you do not need to re-enter the Client Secret: leaving a field blank (or leaving the masked secret untouched) keeps the stored value. Only replace the secret when you have rotated the key in Navan.

## Verifying the connection

The integration includes one health check, **Test Navan Connection**. It requests a small sample of your booking report covering the last 90 days - Navan requires date filters on booking queries, so the check supplies them automatically - and confirms that authentication succeeds and booking data is accessible. Serval also re-runs the health check automatically when you save changes to the connection.

On success: "Successfully connected to Navan Booking Data API and retrieved booking information (\[number] total bookings available)"

On failure (invalid credentials): "Unable to connect to Navan Booking Data API. The OAuth client credentials are invalid or expired. Please verify your Client ID and Client Secret in the Navan integration settings."

<Tip>
  If the connection test is green but a workflow returns no bookings, the date filters are the usual culprit: booking queries effectively require them, and the values must be epoch seconds. See "Booking queries return empty results" below.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="The connection test fails with an authentication error">
    Every failure message starts with "Unable to connect to Navan Booking Data API." For failures Serval recognizes, a status-specific explanation follows; otherwise that base message appears alone. If Navan rejects the credentials (401), the message continues: "The OAuth client credentials are invalid or expired. Please verify your Client ID and Client Secret in the Navan integration settings." If the client lacks permission (403): "The OAuth client is not authorized to access Navan. Please ensure the client has been granted the necessary permissions in Navan." If Navan itself errors (500, 502, or 503): "Navan returned a server error during authentication. This is likely a temporary issue - please try again later."
  </Accordion>

  <Accordion title="I lost the Navan Secret Key">
    Navan only shows the Secret Key in the creation pop-up. There is no way to view it again. Use **Rotate Key** on the credential in Navan's Integrations settings (you get a new secret with the same Client ID), then edit the Serval connection: choose to replace the masked Client Secret and paste the new value.
  </Accordion>

  <Accordion title="The form let me save a blank connection">
    None of the connect form fields are required, so a fully blank first-time submit is accepted by the UI. The problem only shows up when the connection test runs and reports invalid credentials. If this happens, edit the connection and fill in the Client ID and Client Secret.
  </Accordion>

  <Accordion title="Do I need to re-enter the secret when editing the connection?">
    No. The settings screen shows the Client Secret masked (bullet characters plus the last 4 characters), and saving with a blank or untouched secret preserves the stored value - the same applies to the Instance Name and Client ID. Renaming the instance or changing the Client ID alone is safe. Only re-enter the secret when rotating the key in Navan.
  </Accordion>

  <Accordion title="Booking queries return empty results or an error">
    Navan's booking report expects date filters, and all date values must be epoch seconds (whole-number Unix timestamps) - not milliseconds and not ISO date strings. This applies to all six date filters: createdFrom, createdTo, updatedFrom, updatedTo, startDateFrom, and startDateTo. Missing filters or wrong units yield empty results or a request error. The pre-installed workflow and the health check both supply created-date filters automatically.
  </Accordion>

  <Accordion title="Where do I set scopes or my company domain?">
    You don't. Navan does not use explicit scopes - a single bookings-read capability is always included with the credential - and the API host is fixed, so there is no domain or subdomain to enter anywhere in the form.
  </Accordion>

  <Accordion title="Pagination starts at page 0">
    Booking report pages are zero-based: Serval's shipped workflow and health check start at page 0. The pre-installed workflow keeps requesting pages until the reported current page reaches the last page, and treats a response with no total page count as the end of the results. If you build your own pagination, also stop when a page returns fewer rows than you requested.
  </Accordion>

  <Accordion title="Only the booking report is available">
    The integration currently covers a single resource: the company booking report. There is no dedicated single-booking endpoint - to fetch one booking, filter the report by its booking or trip identifier instead - and Navan's people, policy, and invoice APIs are out of scope until they appear in the API specification.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Navan integration.