Invoice Search/Status API

15 minute read

The Invoice Status API is for users that want to retrieve specific information about their invoices from their own applications. The information users may want to retrieve includes:

Invoice status
Reduction/rejection reason
Payment information (date, reference, amount)
Current processing status

This API is designed to:

Allow zero or more defined search terms per request
Allow the user to define specific fields to be returned in each response
Return charge-detail level data with each response

HTTP Method	URL	Authentication Type
POST	/api/v1/invoices/search	Bearer Token

Request Body

Name	Type	Required	Description
searchType	String	Optional	Required if a filterList is not used on the request. Define a single reference type or which you would like to search. Options include: – FP_PRO_NUMBER – FP_BILL_LADING_NUMBER – FP_EDI_INVOICE_NUMBER – TRACKING_NUMBER – FP_CHECK_NUMBER – CONTAINER_NUMBER
searchTerm	String	Optional	A single value to be used as the search term Required if searchType is used in the request.
exactMatch	Boolean	Optional	Search using exactly the value entered for the searchTerm parameter. When used, expected values are True/False without string formatting (ex: “exactMatch”:true). When not sent, False is the default value implied and the query will be a starts with search for each term given
filterList	Array	Optional	Required if searchType is not used on the request. By default, no additional filters are applied to your request. Defining additional parameters in the filterList array will allow you to refine the search results accordingly. Field names should use the Display Name as returned in the Field List API
returnFields	Array	Required	The ID numbers of the fields that will be returned in the response. You must specify at least 1 field to return in the response. For a list of available fields, call the Invoice Search Fields List API
returnChargeDetailFields	Boolean	Optional	When used, expected values are True/False. When not sent, False is the default value implied and the query will not return charge details

Note: When using FP_CHECK_NUMBER as your serchType and you are searching for ACH payment, prepend the 6-digit reference number with “ACH-“, ex “ACH-601234”.

The following parameters are available for use with the filterList array. When a request includes a filterList field, an operator and value must also be sent on the request. Available operators include:

“Equals”
“In”
- When using the “In” operator, an array must be used for the values:
“Between”

Field Value	Type	Description
Client	String	The VTM client code assigned to an invoice.
Carrier Name	String	The carrier name of the carrier assigned to an invoice. For more information on how to retrieve the VTM spelling of a carrier name, refer to the section Carrier Master Data API
Invoice Status	String	The overall processing status of the invoice. Available values include “PAID”, ”PENDING”, ”PROCESSING”, ”REJECTED”
Mode Description	String	The mode assigned to an invoice. Available values include “LTL”, “Truckload”, “Ocean” and more. For more information on all available values for modeDescription, please see the section Mode Master Data API
Terms Description	String	The term assigned to an invoice. Available values include “Prepaid”, “Collect” and more. For more information on all available values for termsDescription, please see the section Terms Master Data API
Direction Description	String	The direction assigned to an invoice. Available values include “Inbound”, “Outbound” and more. For more information on all available values for directionDescription, please see the section Direction Master Data API
Invoice Type	String	The channel through which the invoice was received by VTM. Available values include “EDI”, “PDF”, “Paper”
Origin State	String	The 2-character origin state assigned to the invoice. Ex: “IL”,”TX”,”MI”, etc
Origin Zip Code	String	The origin zip code assigned to the invoice
Destination State	String	The 2-character destination state assigned to the invoice. Ex: “IL”,”TX”,”MI”, etc
Destination Zip Code	String	The origin zip code assigned to the invoice
SCAC Code	String	The SCAC code of the carrier. For more information on how to retrieve the VTM’s record of a carrier’s SCAC code, refer to the section Carrier Master Data API
Custom Mode Description	String	The mode assigned to an invoice (if applicable). Available values include “LTL”, “Truckload”, “Ocean” and more. For more information on all available values for modeDescription, please see the section Mode Master Data API
Payment Date	String	The payment date of an invoice. Values must be formatted like yyyymmdd
Funds Request Date	String	The funds request date of an invoice. Values must be formatted like yyyymmdd
Invoice Date	String	The invoice date of an invoice. Values must be formatted like yyyymmdd
Ship Date	String	The ship date of an invoice. Values must be formatted like yyyymmdd
Delivery Date	String	The delivery date of an invoice. Values must be formatted like yyyymmdd
Due Date	String	The due date of an invoice. Values must be formatted like yyyymmdd Note: for most VTM clients, the due date is the date on or after the invoice will be funds requested. This is not an indication of when the invoice will be paid
Received Date	String	The date VTM received an invoice. Values must be formatted like yyyymmdd

Response Parameters

Responses from the Invoice Status API will contain 2 or 3 parts:

A summary of the results found
- For a full description of the statuses referenced in this documentation, refer to this guide on Invoice Status meanings
The header-level details/result data for each result found
If returnChargeDetails was sent as true, the charge-detail level data for each result found will be returned
- Note that depending on the number of results returned, requesting charge details may significantly slow the response time of your request. Consider requesting charge details only when you are certain there will only be 1 invoice result.

Response Summary Fields

Level	Name	Type	Description
responseSummary	paidCount	Numeric	The count of invoices that are in a PAID status.
responseSummary	rejectedCount	Numeric	The count of invoices that are in a REJECTED status.
responseSummary	pendingCount	Numeric	The count of invoices that are in a PENDING status.
responseSummary	processingCount	Numeric	The count of invoices that are in a PROCESSING status.
responseSummary	notFoundCount	Numeric	The count of search terms for which we could not find at least one matching result.
responseSummary	totalCount	Numeric	The total count of results in any status.
responseSummary	totalPayAmount	Numeric	The total pay amount for all results in all statues.
results	The specific response returned in the results section will vary based on the fields included in the request.

Charge Details Fields

When true, returnChargeDetailFields will return the following fields for each result:

Field Value	Type	Description
chargeSequence	String	The sequence ID for the returned charge details. When an invoice has only 1 sequence/charge, a single row with a “000” sequence will be returned. If an invoice has more than 1 sequence/charge, “000” will not be used. Instead, the first sequence value returned will be “002” and it will increment by 1 for each subsequent charge type.
chargeCode	String	The charge code aligned to the charge. Example: FRT
chargeCodeDescription	String	The description for the charge code. Example: FREIGHT
chargePayAmount	Numeric	The portion of the invoice amount allocated to the charge
chargeGLAccount	String	If maintained, the G/L Account the charge/sequence was coded.

Sample Request – Using a Pro Number Search Only

{
	"searchType": "FP_PRO_NUMBER",
	"searchTerm": "123",
	"returnChargeDetails": false,
	"exactMatch": false,
	"returnFields": [1,3,11,17,18,50]
}

Sample Response – Using a Pro Number Search Only

{
	"searchResults": {
    		"responseSummary": [
      		{
        		"paidCount": 2,
        		"rejectedcount": 0,
        		"pendingCount": 0,
        		"processingCount": 0,
        		"notFoundCount": 0,
        		"totalCount": 2,
        		"totalPayAmount": 494.23
      		}
    		],
    		"results": [
      		{
        		"FP_CLIENT_CODE": "AM001",
        		"FP_PRO_NUMBER": "123456",
        		"FP_TOTAL_PAY_AMOUNT": 394.23,
        		"FP_CHECK_NUMBER": "321574",
        		"FP_CHECK_DATE": "06/25/2025",
        		"FP_PAYMENT_STATUS": "PAID"
		},
      		{
        		"FP_CLIENT_CODE": "AM001",
        		"FP_PRO_NUMBER": "123456BD",
        		"FP_CARRIER_NAME": "LILY TRANSPORTATION LLC",
        		"FP_TOTAL_PAY_AMOUNT": 100,
        		"REASON": "",
        		"FP_CHECK_NUMBER": "ACH-631351",
        		"FP_CHECK_DATE": "10/20/2025",
        		"FP_PAYMENT_STATUS": "PAID"
     		}
    		]
	  }	
}

When no results are found for a request, a response will be returned like:

No results found for this request

Sample Request – Search using a specific pro number search term

{
	"searchType": "FP_PRO_NUMBER",
  	"searchTerm": "123456",
  	"filterList": [
    	{
        	"field": "Invoice Status",
        	"operator": "in",
        	"value1": ["PAID","REJECTED"]
    	}
  	],
  	"returnChargeDetails": false,
  	"returnFields": [1,3,11,17,18,50,12]
}

Sample Response – Search using a specific pro number search term and filters

{
  "searchResults": {
    "responseSummary": [
      {
        "paidCount": 1,
        "rejectedcount": 1,
        "pendingCount": 0,
        "processingCount": 0,
        "notFoundCount": 0,
        "totalCount": 2,
        "totalPayAmount": 1400.00
      }
    ],
    "results": [
      {
        "FP_CLIENT_CODE": "AM001",
        "FP_PRO_NUMBER": "123456",
        "FP_TOTAL_PAY_AMOUNT": 1400.00,
        "FP_CHECK_NUMBER": "361257",
        "FP_CHECK_DATE": "12/18/2023",
        "FP_PAYMENT_STATUS": "PAID",
        "FP_OVERCHARGE_REASON_CODE",""
      },
      {
        "FP_CLIENT_CODE": "AM001",
        "FP_PRO_NUMBER": "123456",
        "FP_TOTAL_PAY_AMOUNT": 0,
        "FP_CHECK_NUMBER": "361257",
        "FP_CHECK_DATE": "12/18/2023",
        "FP_PAYMENT_STATUS": "REJECTED"
        "FP_OVERCHARGE_REASON_CODE","DUPLICATE PRO DETECTED"
      }
    ]
  }
}

When no results are found for a request, a response will be returned like:

No results found for this request

Sample Request – Search using filters only and charge details requested

{
  "filterList": [
    {
        "field": "Client",
        "operator": "in",
        "value1": ["AM001"]
    },
    {
        "field": "Invoice Status",
        "operator": "in",
        "value1": ["PAID"]
    },
    {
        "field": "Carrier Name",
        "operator": "in",
        "value1": ["<Carrier Name>"]
    },
    {
        "field": "Ship Date",
        "operator":"BETWEEN",
        "Value1":["01/01/2024"],
        "Value2":["12/31/2024"]
    }

  ],
  "returnChargeDetails": true,
  "returnFields": [1,3,11,17,18,50,12]
}

Sample Response – Search using filters only and charge details requested

{
  "searchResults": {
    "responseSummary": [
      {
        "paidCount": 1,
        "rejectedcount": 0,
        "pendingCount": 0,
        "processingCount": 0,
        "notFoundCount": 0,
        "totalCount": 1,
        "totalPayAmount": 1045.0
      }
    ],
    "results": [
      {
        "FP_CLIENT_CODE": "AM001",
        "FP_PRO_NUMBER": "11724621452",
        "FP_TOTAL_PAY_AMOUNT": 1045.0,
        "FP_CHECK_NUMBER": "143425",
        "FP_CHECK_DATE": "02/08/2025",
        "FP_PAYMENT_STATUS": "PAID",
        "FP_OVERCHARGE_REASON_CODE": "",
        "chargeDetails": [
          {
            "chargeSequence": "002",
            "chargeCode": "ACC",
            "chargeCodeDescription": "ACCESSORIAL CHARGE",
            "chargePayAmount": 695.0,
            "chargeGLAccount": "0400354440001652241"
          },
          {
            "chargeSequence": "003",
            "chargeCode": "FRT",
            "chargeCodeDescription": "FREIGHT",
            "chargePayAmount": 350.0,
            "chargeGLAccount": "0400354440001652241"
          }
        ]
      }
    ]
  }
}

Updated on November 5, 2025

What are your Feelings

Happy
Normal
Sad

Transware APIs

Claim APIs

Master Data APIs

Invoice APIs