Navix Public API (v1-v2)

To begin working with the Navix API, you'll need the following. Your Navix customer success manager will provide you with these details:

• Tenant UUID. We generally set up both a production tenant and a sandbox tenant. We'll send you the UUIDs for both the production and sandbox tenant.
• User account. You can use this account to log in to the Navix UI to help test your API interactions.
• API key. We’ll send you an API key used to authenticate.

Every API request should include an X-Tenant-Uuid header that contains your Tenant UUID and an X-Api-Key header containing your API key.

Our APIs are generally broken into three categories:

• v1: This is the original version of our API. We plan to continue supporting it without breaking changes, but most new development will occur on v2.
• v2: This introduced several improvements to our API, but also introduced some breaking changes. The major change is that it supports multiple vendors and multiple invoices on a single order. We're committed to stability on these endpoints, we support them and won't make breaking changes to them.
• Provisional: We want to make sure our customers always have access to the latest features we're building. Our provisional endpoints provide a glimpse into the latest and greatest. However, these endpoints are not generally available and should not be used without explicit authorization for your Navix account team.

⚠️ Provisional Endpoints Support

Do not use provisional endpoints unless you've been explicitly authorized to use them by your Navix account team. Outside of authorized, tenant-specific use cases, we will not provide support for these endpoints, and their use could have unintended side effects.

Note that additive changes to an endpoint are not considered breaking. For instance, adding a new property to an endpoint isn't considered breaking, since the API consumer should ignore unknown properties by default. Likewise, it's important for API consumers not to send any data that isn't documented here. Although we ignore unrecognized fields, sending an unsupported property could cause a conflict if we later add a new property with that name.

Note that some of our API endpoints operate asynchronously and may not be instantaneous. There are a number of reasons for this. Usually, these operations end up in a queue, providing greater resiliency. Sometimes, there's a multiple step workflow that takes a bit of time to run. Either way, we want our endpoint to validate the request and quickly return a response indicating if there are any errors.

Following RESTful best practices, our asynchronous endpoints return a 202 Accepted response, rather than a 200 OK. For instance, when creating an order (with POST /v2/orders), several validations are run; if any of them fail, a 400 Bad Request is returned with additional detail on which validations failed. If the POSTed data is valid, a 202 Accepted is returned, which indicates the order will be added to our queue of orders to import. The order may not immediately appear within other API requests or within the UI. Usually, these asynchronous operations run within seconds; occasionally, such as during usage spikes, it may take longer.

Below are some terms (in bold) that have specific meaning in Navix, listed with some synonyms commonly used in the industry.

• Tenant: You, a Navix customer; likely a broker or 3PL
• Order: Load, shipment, movement
• Invoice: Vendor bill, carrier invoice, AP invoice, vendor invoice
• Vendor: Carrier, warehouse, anyone that you pay
• Customer: Shipper, freight forwarder, anyone that pays you
• Document: Anything sent from your vendor; could be: invoice, bill of lading, delivery receipts, packing slips, etc

Some additional terms used in this document:

• Approved Invoice: An invoice that has been audited and approved for payment.
• Terminated Invoice: An invoice that has been rejected for payment.
• Finalized Invoice: An invoice that has been audited and is either "approved" or "terminated".

The primary consumers of this API are tenant's TMS integrations (or the TMS itself). Throughout this section, we refer to "TMS" (Transportation Management System) -- but this could be any consumer of the Navix API.

Navix's API is flexible, and there are multiple ways a TMS can integrate with it. This section focuses on the most common scenarios.

A simple TMS integration has two integration points with Navix:

• TMS pushes orders to Navix.
• TMS pulls completed audits from Navix.

A more complex integration may have several integration points with Navix:

• TMS pushes orders to Navix.
• TMS pushes invoices to Navix.
• TMS pushes supporting documents to Navix.
• Navix calls the TMS rating engine.
• TMS pulls completed audits from Navix.
• TMS pulls supporting documents from Navix.
• TMS pulls dispute data and communications from Navix.

It's worth noting that there may be data (usually invoices and supporting documents) that are being sent to Navix without going through the TMS. For instance, vendors (carriers) may be sending EDI 210 documents directly to Navix. Vendors may also be sending invoices and supporting documents via email.

In order to audit an invoice in Navix, Navix needs to know what order the invoice is for.

Use the "Create an order" (V2) endpoint to push an order to Navix.

We recommend:

• The TMS should push order data to Navix regularly.
• This could happen on a scheduled basis (perhaps every 15 minutes or every hour).
• It can also happen in real-time (whenever a load/order is changed in the TMS).
• Only orders that have been changed should be pushed to Navix.
• Push orders to Navix after they have been tendered to a carrier, before the point in time when Navix may start receiving invoices.
• You can push an order to Navix multiple times. Navix will perform an upsert based on the orderNumber. That is, if you push an order to Navix, if there's an existing order with the same orderNumber, it will be updated instead of inserted.
• Send an externalId that correlates to the unique identifier for the order in the TMS.

We recommend against:

• Sending all open orders on a scheduled basis. (For instance, sending all tendered orders every hour, regardless of whether or not anything has been changed on the order.)
• Storing or relying on order UUIDs. An order UUID refers to a specific version of the order data; subsequent updates/upserts will result in new order UUIDs.
• Assuming the order will be ingested immediately. Order ingestion generally occurs in near real-time. However, due to the resilient and distributed nature of our system, ingestion can occasionally take longer.

When an audit has been completed (either by a user or automatically by Navix), the TMS needs to know the results of the audit.

There are two ways to manage this:

• Polling: On a scheduled basis, the TMS polls the Navix API for any invoices that have been approved since the last polling.
• Webhook: Whenever an invoice is approved, Navix will call a webhook callback on an API hosted by the TMS.

Either way, the only data the TMS gets from either polling or a webhook is the UUID of an invoice that's been approved. The next step is to get the audit results.

Polling

Use the "List finalized invoices" endpoint to get a list of invoices finalized during a given time period.

Notes:

• The results are paged. More than one page of results may be returned; be sure to check to see if there are additional pages.
• It's the responsibility of the TMS to keep track of the last time polling was run, and to set the StartTime and EndTime accordingly. If the TMS misses a scheduled run, the next poll request should adjust the StartTime accordingly.
• Note that the StartTime and EndTime are UTC, and are the times stored by Navix. We recommend planning for a small amount of "clock drift" -- that is, the time on your server might vary slightly from the times on Navix servers. So if you're running this process at 6:00:00 UTC, it might make sense to specify an EndTime of 5:59:00 UTC.
• You can poll with whatever frequency you want. Most tenants find that polling every 10-15 minutes strikes a good balance between returning results quickly and avoiding an overly "chatty" integration.

Webhook

Use the INVOICE_APPROVED webhook to receive a webhook callback whenever an invoice is approved.

Notes:

• Webhooks are triggered in real-time. So as soon as an invoice is approved, your callback URL will be immediately hit.
• It's the responsibility of the TMS to handle the volume or fail in a prescribed fashion. Invoices are often approved in bulk, so there could be dozens, hundreds, or even thousands of webhook callbacks triggered in a very short period of time. Review the section on webhook delivery guarantees for more details on how Navix will retry webhooks.
• Depending on the reliability of the TMS, it may be beneficial to supplement webhooks with occasional polling. That is, if there's a chance that the callback may fail or the TMS may miss some webhooks, the polling endpoint can be used to verify if any webhooks failed.

Getting Audit Results

Once you've received the UUID of an approved invoice, either by polling or webhook, use the "Get audit result" endpoint to get the results of an audit.

Notes:

• Make sure to use the latest (v2) version of the "Get audit result" endpoint.

After the TMS has pulled audit results for an invoice, it can retrieve the supporting documents for the invoice. Use the "Download invoice document" endpoint to download the raw file.

Notes:

• The endpoint requires an invoice UUID and a document UUID. Document UUIDs are returned in the "Get audit result" endpoint, under orders.documents.uuid.
• Additional information about the document is available from the "Get result endpoint", such as the type of document ("Invoice", "Bill of Lading", etc.).
• The endpoint returns the raw binary file.
• Currently, all returned files will be in PDF format. However, this may change in the future, and API consumers should not assume that the returned files will always be PDFs.

A webhook is a callback mechanism that causes Navix to make an API request to a consumer system when events occur within Navix.

Our webhooks are "thin". That is, they're lightweight and usually contain IDs that can be used to retreive additional data via API.

All webhooks have the same payload structure as this example:

{
    "id": "00000000-0000-0000-0000-000000000000",
    "type": "DISPUTE_CREATED",
    "time": "1/1/1970 00:00:00Z",
    "data": "\{ \"invoiceUuid\": \"<uuid>\" \}"
}

• id is a unique identifier for the event. Note that this is not the identifier for the object (invoice, dispute, etc.) which triggered the event.
• type is the specific type of event that triggered the webhook. Possible values include:
  • INVOICE_CREATED
  • INVOICE_APPROVED
  • DISPUTE_CREATED
  • DISPUTE_UPDATED
  • DISPUTE_COMMUNICATION_CREATED
• time is the UTC time of when the event occurred.
• data contains a JSON object with details for the event. The specific data varies depending on the type of event that occurred. Note that the JSON has been escaped.

The webhook consumer should return a status code between 200 and 299 (inclusive) within about 20 seconds.

If the consumer is unreachable, doesn't respond promptly, or returns a status code less than 200 or greater than 299, we will consider the delivery attempt failed and will make another attempt.

We use an exponential backoff algorithm to determine the time between delivery attempts, starting at a few seconds and increasing to a maximum of 1 hour. We will continue to attempt delivery for 8 hours beyond the initial attempt, after which the message will be discarded.

We aim for at-least-once delivery, so a single event may hit the webhook receiver multiple times. When that occurs, the id will be the same across the multiple requests, so it can be used as an idempotency key by consumers.

We cannot guarantee that webhooks will arrive in order. That is, if a dispute is updated twice, the webhook for the second update could arrive before the first. If that's likely to cause issues, we recommend recording the time field on the webhook and comparing that stored time to the time on any received webhook.

INVOICE_CREATED

This event is raised whenever an invoice is created.

data object

{
  "invoiceUuid": "00000000-0000-0000-0000-000000000000"
}

• invoiceUuid is the identifier for the invoice which was created.

INVOICE_APPROVED

This event is raised whenever an invoice is approved. Note that this is only raised for approvals, not for terminated invoices.

data object

{
  "invoiceUuid": "00000000-0000-0000-0000-000000000000"
}

• invoiceUuid is the identifier for the invoice which was approved.

DISPUTE_CREATED

This event is raised whenever a new dispute is created.

data object

{
  "invoiceUuid": "00000000-0000-0000-0000-000000000000",
  "disputeUuid": "00000000-0000-0000-0000-000000000000"
}

• invoiceUuid is the identifier for the invoice on which the dispute was created.
• disputeUuid is the identifier for the newly created dispute.

DISPUTE_UPDATED

This event is raised whenever a dispute is updated. Note that creating and updating are separate events, so this event isn't raised when the dispute is initially created.

data object

{
  "invoiceUuid": "00000000-0000-0000-0000-000000000000",
  "disputeUuid": "00000000-0000-0000-0000-000000000000"
}

• invoiceUuid is the identifier for the invoice associated with the dispute that was updated.
• disputeUuid is the identifier for the updated dispute.

DISPUTE_COMMUNICATION_CREATED

This event is raised whenever a new communication is created on a dispute.

Communications are immutable, so there's no corresponding webhook for updates to a communication.

Note that whenever a dispute is created, an initial communication is usually created at the same time. It's possible the DISPUTE_COMMUNICATION_CREATED webhook will arrive before the DISPUTE_CREATED webhook.

data object

{
  "invoiceUuid": "00000000-0000-0000-0000-000000000000",
  "disputeUuid": "00000000-0000-0000-0000-000000000000",
  "communicationUuid": "00000000-0000-0000-0000-000000000000"
}

• invoiceUuid is the identifier for the invoice associated with the dispute.
• disputeUuid is the identifier for the dispute.
• communicationUuid is the identifier for the created communication.