List company custom fields (the mechanism Navan uses for cost-center, department, and GL coding), read a single field definition, batch-manage a field's options, and poll asynchronous option-management jobs. Endpoints confirmed against the Navan Expense API reference.
openapi: 3.0.3
info:
title: Navan API
description: >-
The Navan API is the public developer surface for the Navan (formerly
TripActions) corporate travel, expense, and corporate card platform. It is a
REST/HTTPS API secured with OAuth 2.0 using the client-credentials grant.
Administrators generate a client_id / client_secret in the Navan app under
Settings > Integrations (API), exchange them for a Bearer access token, and
call the API with `Authorization: Bearer <token>`. Access is scoped
(e.g. bookings:read, users:read, users:write, users:delete, and the expense
read/write scopes).
Endpoint status: the Expense API paths (transactions, fees, adjustments,
receipts, custom fields) and the travel/v1 Users paths are CONFIRMED against
Navan's published API reference and third-party integration guides. The
Bookings and Webhook subscription-management paths are MODELED - the relevant
scopes and capabilities are documented by Navan, but the exact request paths
are behind a gated reference and are represented here as a best-effort model.
Modeled operations are flagged with `x-endpoint-status: modeled`.
version: '1.0'
contact:
name: Navan Developers
url: https://developer.navan.com/
x-rebrand-note: >-
Navan was known as TripActions until its February 2022 rebrand to Navan;
some legacy hostnames and token paths still carry a `ta-` (TripActions)
prefix, e.g. the `ta-auth` OAuth token path.
servers:
- url: https://api.navan.com
description: Navan API (US / global)
security:
- oauth2ClientCredentials: []
tags:
- name: Transactions
description: Expense transactions across Navan card, Connect, manual, and repayment types. CONFIRMED.
- name: Fees and Adjustments
description: Fees, credit/debit adjustments, daily rebates, and disputes. CONFIRMED.
- name: Receipts
description: Receipt URLs and downloads for expense transactions. CONFIRMED.
- name: Custom Fields
description: Company custom fields used for cost-center / GL coding. CONFIRMED.
- name: Users
description: User provisioning and lifecycle under travel/v1. CONFIRMED.
- name: Bookings
description: Booking (trip) records for downstream reporting. MODELED.
- name: Webhooks
description: Webhook subscription management for change notifications. MODELED.
paths:
# ---------------- Transactions (CONFIRMED) ----------------
/v1/expense/transactions:
get:
operationId: listTransactions
tags: [Transactions]
summary: List transactions
description: Generic multi-type retrieval of expense transactions. CONFIRMED.
parameters:
- $ref: '#/components/parameters/FromDate'
- $ref: '#/components/parameters/ToDate'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/PageSize'
responses:
'200':
description: A page of transactions.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionList'
'401':
$ref: '#/components/responses/Unauthorized'
patch:
operationId: updateTransactions
tags: [Transactions]
summary: Batch update transactions
description: Batch-update a set of transactions (for example custom-field coding). CONFIRMED.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionBatchUpdate'
responses:
'200':
description: Update result.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionList'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/v1/expense/transactions/{id}:
parameters:
- $ref: '#/components/parameters/TransactionId'
get:
operationId: getTransaction
tags: [Transactions]
summary: Get a transaction
description: Retrieve a single transaction by its ID. CONFIRMED.
responses:
'200':
description: The requested transaction.
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/expense/card-transactions:
get:
operationId: listCardTransactions
tags: [Transactions]
summary: List Navan card transactions
description: Retrieve transactions made on Navan-issued corporate cards. CONFIRMED.
parameters:
- $ref: '#/components/parameters/FromDate'
- $ref: '#/components/parameters/ToDate'
- $ref: '#/components/parameters/Cursor'
responses:
'200':
description: A page of card transactions.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionList'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/expense/connect-transactions:
get:
operationId: listConnectTransactions
tags: [Transactions]
summary: List Connect card transactions
description: Retrieve transactions from Navan Connect external card integrations. CONFIRMED.
parameters:
- $ref: '#/components/parameters/FromDate'
- $ref: '#/components/parameters/ToDate'
- $ref: '#/components/parameters/Cursor'
responses:
'200':
description: A page of Connect transactions.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionList'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/expense/manual-transactions:
get:
operationId: listManualTransactions
tags: [Transactions]
summary: List manual transactions
description: Retrieve manual submissions and payroll transactions. CONFIRMED.
parameters:
- $ref: '#/components/parameters/FromDate'
- $ref: '#/components/parameters/ToDate'
- $ref: '#/components/parameters/Cursor'
responses:
'200':
description: A page of manual transactions.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionList'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/expense/repayments:
get:
operationId: listRepayments
tags: [Transactions]
summary: List repayments
description: Retrieve user repayment transactions. CONFIRMED.
parameters:
- $ref: '#/components/parameters/FromDate'
- $ref: '#/components/parameters/ToDate'
- $ref: '#/components/parameters/Cursor'
responses:
'200':
description: A page of repayments.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionList'
'401':
$ref: '#/components/responses/Unauthorized'
# ---------------- Fees and Adjustments (CONFIRMED) ----------------
/v1/expense/fees:
get:
operationId: listFees
tags: [Fees and Adjustments]
summary: List fees
description: Retrieve direct-reimbursement, FX, and platform fees. CONFIRMED.
parameters:
- $ref: '#/components/parameters/FromDate'
- $ref: '#/components/parameters/ToDate'
responses:
'200':
description: A page of fees.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionList'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/expense/adjustments:
get:
operationId: listAdjustments
tags: [Fees and Adjustments]
summary: List adjustments
description: Retrieve credit and debit memo adjustments. CONFIRMED.
parameters:
- $ref: '#/components/parameters/FromDate'
- $ref: '#/components/parameters/ToDate'
responses:
'200':
description: A page of adjustments.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionList'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/expense/daily-rebates:
get:
operationId: listDailyRebates
tags: [Fees and Adjustments]
summary: List daily rebates
description: Retrieve daily rebate transactions. CONFIRMED.
parameters:
- $ref: '#/components/parameters/FromDate'
- $ref: '#/components/parameters/ToDate'
responses:
'200':
description: A page of daily rebates.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionList'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/expense/disputes:
get:
operationId: listDisputes
tags: [Fees and Adjustments]
summary: List disputes
description: Retrieve dispute transactions. CONFIRMED.
parameters:
- $ref: '#/components/parameters/FromDate'
- $ref: '#/components/parameters/ToDate'
responses:
'200':
description: A page of disputes.
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionList'
'401':
$ref: '#/components/responses/Unauthorized'
# ---------------- Receipts (CONFIRMED) ----------------
/v1/expense/transactions/{id}/receipt:
parameters:
- $ref: '#/components/parameters/TransactionId'
get:
operationId: getTransactionReceipt
tags: [Receipts]
summary: Get receipt URLs for a transaction
description: Retrieve receipt image URLs for a given transaction. CONFIRMED.
responses:
'200':
description: Receipt URLs.
content:
application/json:
schema:
$ref: '#/components/schemas/ReceiptList'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/expense/transactions/{id}/receipt/download:
parameters:
- $ref: '#/components/parameters/TransactionId'
get:
operationId: downloadTransactionReceipt
tags: [Receipts]
summary: Download a transaction receipt
description: Follow a redirect to download the receipt file for a transaction. CONFIRMED.
responses:
'302':
description: Redirect to the receipt file.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/expense/transactions/receipts:
get:
operationId: listReceipts
tags: [Receipts]
summary: Batch list receipt URLs
description: Batch-fetch receipt URLs across transactions filtered by date. CONFIRMED.
parameters:
- $ref: '#/components/parameters/FromDate'
- $ref: '#/components/parameters/ToDate'
responses:
'200':
description: Receipt URLs across transactions.
content:
application/json:
schema:
$ref: '#/components/schemas/ReceiptList'
'401':
$ref: '#/components/responses/Unauthorized'
# ---------------- Custom Fields (CONFIRMED) ----------------
/v1/expense/custom-fields:
get:
operationId: listCustomFields
tags: [Custom Fields]
summary: List custom fields
description: List all company custom fields. CONFIRMED.
responses:
'200':
description: A list of custom fields.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/CustomField'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/expense/custom-fields/{fieldName}:
parameters:
- $ref: '#/components/parameters/FieldName'
get:
operationId: getCustomField
tags: [Custom Fields]
summary: Get a custom field
description: Retrieve a single custom field definition by name. CONFIRMED.
responses:
'200':
description: The requested custom field.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomField'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/expense/custom-fields/{fieldName}/options:
parameters:
- $ref: '#/components/parameters/FieldName'
post:
operationId: manageCustomFieldOptions
tags: [Custom Fields]
summary: Batch manage custom field options
description: Batch-create or update the options (values) available on a custom field. CONFIRMED.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldOptionsInput'
responses:
'200':
description: Job accepted (may run asynchronously).
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/v1/expense/custom-fields/jobs/{job_id}:
parameters:
- name: job_id
in: path
required: true
description: The asynchronous job ID returned by an options-management request.
schema:
type: string
get:
operationId: getCustomFieldJob
tags: [Custom Fields]
summary: Get custom field job status
description: Poll the status of an asynchronous custom-field options job. CONFIRMED.
responses:
'200':
description: Job status.
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
# ---------------- Users (CONFIRMED) ----------------
/travel/v1/users:
get:
operationId: listUsers
tags: [Users]
summary: List users
description: List users with cursor-based pagination. Requires users:read. CONFIRMED.
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/PageSize'
responses:
'200':
description: A page of users.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
next_cursor:
type: string
nullable: true
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createUser
tags: [Users]
summary: Create a user
description: Create a new user. Requires users:write. CONFIRMED.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserInput'
responses:
'200':
description: The created user.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/travel/v1/users/{userId}:
parameters:
- $ref: '#/components/parameters/UserId'
get:
operationId: getUser
tags: [Users]
summary: Get a user
description: Retrieve a user by ID. Requires users:read. CONFIRMED.
responses:
'200':
description: The requested user.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
patch:
operationId: updateUser
tags: [Users]
summary: Update a user
description: Update a user record. Requires users:write. CONFIRMED.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserInput'
responses:
'200':
description: The updated user.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/ValidationError'
delete:
operationId: deactivateUser
tags: [Users]
summary: Deactivate a user
description: Soft-delete (deactivate) a user account. Requires users:delete. CONFIRMED.
responses:
'200':
description: Deactivation confirmation.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
# ---------------- Bookings (MODELED) ----------------
/travel/v1/bookings:
get:
operationId: listBookings
tags: [Bookings]
summary: List bookings
description: >-
List booking (trip) records for downstream reporting and ERP transfer.
The bookings:read scope is confirmed; the path and query parameters are
MODELED from Navan's booking-data integration documentation.
x-endpoint-status: modeled
parameters:
- $ref: '#/components/parameters/FromDate'
- $ref: '#/components/parameters/ToDate'
- $ref: '#/components/parameters/Cursor'
responses:
'200':
description: A page of bookings.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Booking'
next_cursor:
type: string
nullable: true
'401':
$ref: '#/components/responses/Unauthorized'
/travel/v1/bookings/{bookingId}:
parameters:
- name: bookingId
in: path
required: true
description: The booking (trip) identifier.
schema:
type: string
get:
operationId: getBooking
tags: [Bookings]
summary: Get a booking
description: >-
Retrieve a single booking by ID. MODELED - path inferred from the
booking-data integration surface; verify against the gated reference.
x-endpoint-status: modeled
responses:
'200':
description: The requested booking.
content:
application/json:
schema:
$ref: '#/components/schemas/Booking'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
# ---------------- Webhooks (MODELED) ----------------
/v1/expense/webhooks:
get:
operationId: listWebhooks
tags: [Webhooks]
summary: List webhook subscriptions
description: >-
List configured webhook subscriptions. Navan documents webhooks as a
first-class Expense API feature; the subscription-management path is
MODELED because the detailed reference is gated.
x-endpoint-status: modeled
responses:
'200':
description: A list of webhook subscriptions.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Webhook'
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createWebhook
tags: [Webhooks]
summary: Create a webhook subscription
description: Register a webhook endpoint to receive change notifications. MODELED.
x-endpoint-status: modeled
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookInput'
responses:
'200':
description: The created webhook subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/v1/expense/webhooks/{id}:
parameters:
- name: id
in: path
required: true
description: The webhook subscription ID.
schema:
type: string
get:
operationId: getWebhook
tags: [Webhooks]
summary: Get a webhook subscription
description: Retrieve a webhook subscription by ID. MODELED.
x-endpoint-status: modeled
responses:
'200':
description: The requested webhook subscription.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteWebhook
tags: [Webhooks]
summary: Delete a webhook subscription
description: Delete a webhook subscription. MODELED.
x-endpoint-status: modeled
responses:
'200':
description: Deletion confirmation.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
securitySchemes:
oauth2ClientCredentials:
type: oauth2
description: >-
OAuth 2.0 client-credentials flow. Generate a client_id / client_secret
in the Navan app under Settings > Integrations (API), then POST
grant_type=client_credentials to the token URL to obtain a Bearer access
token. US token URL: https://app.navan.com/ta-auth/oauth/token ;
EU token URL: https://app-fra.navan.com/ta-auth/oauth/token . (Some
integrations reference an https://api.navan.com/ta-auth/oauth/token or
/auth/v1/token variant; confirm the current token URL in the Navan
developer portal.)
flows:
clientCredentials:
tokenUrl: https://app.navan.com/ta-auth/oauth/token
scopes:
bookings:read: Read booking (trip) data.
users:read: Read user profiles.
users:write: Create and modify users.
users:delete: Deactivate users.
liquid:read: Read expense data (transactions, fees, receipts, custom fields).
liquid:write: Update expense data.
parameters:
Cursor:
name: cursor
in: query
required: false
description: Opaque cursor for pagination.
schema:
type: string
PageSize:
name: page_size
in: query
required: false
description: Maximum number of records to return per page.
schema:
type: integer
FromDate:
name: from
in: query
required: false
description: Start of the date range filter (ISO 8601).
schema:
type: string
format: date-time
ToDate:
name: to
in: query
required: false
description: End of the date range filter (ISO 8601).
schema:
type: string
format: date-time
TransactionId:
name: id
in: path
required: true
description: The transaction identifier.
schema:
type: string
FieldName:
name: fieldName
in: path
required: true
description: The custom field name.
schema:
type: string
UserId:
name: userId
in: path
required: true
description: The user identifier.
schema:
type: string
responses:
Unauthorized:
description: Missing or invalid access token, or insufficient scope.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ValidationError:
description: The request payload failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
details:
type: object
additionalProperties: true
DeleteResponse:
type: object
properties:
id:
type: string
deactivated:
type: boolean
Transaction:
type: object
properties:
id:
type: string
type:
type: string
description: The transaction type (card, connect, manual, repayment, fee, adjustment, rebate, dispute).
status:
type: string
merchant:
type: string
amount:
type: number
currency:
type: string
date:
type: string
format: date-time
userId:
type: string
customFieldValues:
type: object
additionalProperties: true
TransactionList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Transaction'
next_cursor:
type: string
nullable: true
TransactionBatchUpdate:
type: object
required:
- transactions
properties:
transactions:
type: array
items:
type: object
properties:
id:
type: string
customFieldValues:
type: object
additionalProperties: true
Receipt:
type: object
properties:
transactionId:
type: string
url:
type: string
format: uri
fileName:
type: string
contentType:
type: string
ReceiptList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Receipt'
CustomField:
type: object
properties:
name:
type: string
label:
type: string
type:
type: string
required:
type: boolean
options:
type: array
items:
type: string
CustomFieldOptionsInput:
type: object
required:
- options
properties:
options:
type: array
items:
type: object
properties:
value:
type: string
action:
type: string
enum:
- add
- update
- remove
Job:
type: object
properties:
job_id:
type: string
status:
type: string
enum:
- pending
- running
- completed
- failed
User:
allOf:
- $ref: '#/components/schemas/UserInput'
- type: object
properties:
id:
type: string
status:
type: string
enum:
- active
- deactivated
UserInput:
type: object
required:
- email
properties:
email:
type: string
format: email
givenName:
type: string
familyName:
type: string
employeeId:
type: string
department:
type: string
costCenter:
type: string
managerEmail:
type: string
format: email
Booking:
type: object
description: A booking (trip) record. MODELED schema.
properties:
id:
type: string
type:
type: string
enum:
- flight
- hotel
- car
- rail
travelerId:
type: string
status:
type: string
totalAmount:
type: number
currency:
type: string
startDate:
type: string
format: date-time
endDate:
type: string
format: date-time
customFieldValues:
type: object
additionalProperties: true
Webhook:
allOf:
- $ref: '#/components/schemas/WebhookInput'
- type: object
properties:
id:
type: string
WebhookInput:
type: object
required:
- url
- events
properties:
url:
type: string
format: uri
events:
type: array
items:
type: string
secret:
type: string
description: Signing secret used to verify webhook payload authenticity.