---
updatedAt: 2026-05-29T11:03:35.000Z
agentTools:
  projectIndex: https://docs.fonoa.com/llms.txt
---

# Get a list of transactions

Used to search for transactions.

# OpenAPI definition

```json
{
  "components": {
    "schemas": {
      "OperationResultResponse": {
        "properties": {
          "errors": {
            "description": "List of errors in case the request was unsuccessful.",
            "items": {
              "$ref": "#/components/schemas/TransactionErrorResponse"
            },
            "type": "array"
          },
          "message": {
            "description": "Information about the failure reason in case the request was unsuccessful.",
            "type": "string"
          },
          "operation_id": {
            "description": "Auto-generated unique identifier of a transaction operation returned upon async operation request.",
            "type": "string"
          },
          "transaction_id": {
            "description": "The unique external transaction identifier provided with the initial request.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "SearchDashboardTransaction": {
        "properties": {
          "backfill": {
            "description": "Indicates whether the transaction is a backfill.",
            "type": "boolean"
          },
          "country_code": {
            "description": "ISO 3166-1 alpha-2 uppercase country code of the country where the transaction was reported.",
            "type": "string"
          },
          "currency_code": {
            "description": "Primary currency code of the transaction represented as ISO 4217 3 letter uppercase currency code e.g. `USD`.",
            "type": "string"
          },
          "customer": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SearchTransactionCustomerResponse"
              }
            ],
            "description": "Transaction customer information.",
            "type": "object"
          },
          "data_source": {
            "description": "Indicates the input source of the transaction, e.g. `API`, `CSV`.",
            "type": "string"
          },
          "direction": {
            "description": "Document representing a transaction can be sent or received. Allows businesses to report both inbound and outbound transactions for VAT deduction purposes. Default: `SENT`.",
            "type": "string"
          },
          "errors": {
            "description": "List of errors while processing the transaction.",
            "items": {
              "$ref": "#/components/schemas/TransactionErrorResponse"
            },
            "type": "array"
          },
          "last_updated_date": {
            "description": "RFC3339 datetime string representing the last point in time of a transaction update.",
            "type": "string"
          },
          "operation_id": {
            "description": "The unique Fonoa identifier of a transaction request/operation.",
            "type": "string"
          },
          "reporting_date": {
            "description": "RFC3339 datetime string representing the point in time when transaction is reported.",
            "type": "string"
          },
          "status": {
            "description": "Status of the transaction.",
            "type": "string"
          },
          "supplier": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SearchTransactionSupplierResponse"
              }
            ],
            "description": "Transaction supplier information.",
            "type": "object"
          },
          "tax_reason": {
            "allOf": [
              {
                "$ref": "#/components/schemas/TransactionTaxReason"
              }
            ],
            "description": "Tax reason carried on business-response transactions (buyer acceptance/refusal), e.g. code `REFUSAL` with description and jurisdiction-specific details. Empty for other transactions.",
            "type": "object"
          },
          "total_amount": {
            "description": "Total amount (net + tax) for the entire transaction",
            "type": "number"
          },
          "total_net_amount": {
            "description": "Total net amount for the entire transaction.",
            "type": "number"
          },
          "total_tax_amount": {
            "description": "Total tax amount for the entire transaction",
            "type": "number"
          },
          "transaction_date": {
            "description": "RFC3339 datetime string representing the point in time when transaction is executed.",
            "type": "string"
          },
          "transaction_id": {
            "description": "External transaction identifier provided by the customer.",
            "type": "string"
          },
          "transaction_number": {
            "description": "Transaction number for the transaction.",
            "type": "string"
          },
          "transaction_scenario": {
            "description": "Represents the type of document that needs to be issued depending on the transaction debiting or crediting effect on the TA",
            "type": "string"
          },
          "type": {
            "description": "Type of the transaction that usually depends on transaction value and business model (B2B or B2C).\n\nThe most common types are FULL, SIMPLIFIED, RECEIPT, RECEIPT_INVOICE.",
            "type": "string"
          },
          "user_activities": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SearchTransactionUserActivitiesResponse"
              }
            ],
            "description": "Details of the user activities for the transaction.",
            "type": "object"
          },
          "workflow_operations": {
            "description": "List of possible operations for a transactions.",
            "items": {
              "$ref": "#/components/schemas/WorkflowOperation"
            },
            "type": "array"
          },
          "workflow_status": {
            "description": "Status of the transaction workflow.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "SearchTransactionCustomerResponse": {
        "properties": {
          "external_id": {
            "description": "External (clients) unique identifier for the customer.",
            "type": "string"
          },
          "id": {
            "description": "Fonoa unique identifier for the customer.",
            "type": "string"
          },
          "name": {
            "description": "Customer name.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "SearchTransactionSupplierResponse": {
        "properties": {
          "country_code": {
            "description": "ISO 3166-1 alpha-2 uppercase country code of the country where supplier is registered.",
            "type": "string"
          },
          "external_id": {
            "description": "External (clients) unique identifier for the supplier.",
            "type": "string"
          },
          "id": {
            "description": "Fonoa unique identifier for the supplier.",
            "type": "string"
          },
          "name": {
            "description": "Supplier name.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "SearchTransactionUserActivitiesResponse": {
        "properties": {
          "invoice_downloaded": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SearchTransactionUserActivityResponse"
              }
            ],
            "description": "Details of the invoice downloaded activity.",
            "type": "object"
          }
        },
        "type": "object"
      },
      "SearchTransactionUserActivityResponse": {
        "properties": {
          "time": {
            "description": "Date and time in UTC in format RFC3339. e.g. 2022-03-31T23:59:59Z when the action was performed.",
            "type": "string"
          },
          "type": {
            "description": "Activity type. Allowed values: `INVOICE_DOWNLOADED`",
            "type": "string"
          },
          "user_id": {
            "description": "ID of the user that performed the action",
            "type": "string"
          }
        },
        "type": "object"
      },
      "SearchTransactionsResponse": {
        "properties": {
          "limit": {
            "type": "integer"
          },
          "next_cursor": {
            "type": "string"
          },
          "transactions": {
            "items": {
              "$ref": "#/components/schemas/SearchDashboardTransaction"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "TransactionErrorResponse": {
        "properties": {
          "code": {
            "description": "Error code of the issue. e.g., field_not_valid",
            "type": "string"
          },
          "doc_link": {
            "description": "The link for the error documentation. Follow it to gather more details about the error",
            "type": "string"
          },
          "field": {
            "description": "Field from the input request that caused the error, in case of validation errors. e.g. transaction_date",
            "type": "string"
          },
          "message": {
            "description": "Error message of the issue. e.g., Date must be in RFC3339 format.",
            "type": "string"
          },
          "type": {
            "description": "Error type of the issue. e.g., warning, validation, general, tax_authority",
            "type": "string"
          }
        },
        "type": "object"
      },
      "TransactionTaxReason": {
        "properties": {
          "code": {
            "description": "The specific code to be used as the tax reason for the transaction. e.g., S01 - indicating no tax effect in Mexican jurisdiction\n\nValidations:\n- Maximum length: 15\n- Required property",
            "example": "S01",
            "type": "string"
          },
          "description": {
            "description": "Further explanation of the tax reason for the code provided\n\nValidations:\n- Maximum length: 450",
            "example": "S01",
            "type": "string"
          },
          "tax_reason_details": {
            "description": "Additional details to be provided for the tax reason code.\n\nValidations:\n- This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.",
            "items": {
              "$ref": "#/components/schemas/TransactionTaxReasonDetail"
            },
            "type": "array"
          }
        },
        "required": [
          "code"
        ],
        "type": "object"
      },
      "TransactionTaxReasonDetail": {
        "properties": {
          "code": {
            "description": "Additional code that complements the tax reason code. For example, specific refusal code for refusal tax reason.\n\nValidations:\n- Maximum length: 30",
            "example": "S01",
            "type": "string"
          },
          "note": {
            "description": "Further explanation of the tax reason detail for the code provided\n\nValidations:\n- Maximum length: 450",
            "example": "S01",
            "type": "string"
          }
        },
        "type": "object"
      },
      "WorkflowOperation": {
        "properties": {
          "status": {
            "description": "Status of the operation. Allowed values: `UNSPECIFIED`, `PENDING`, `PROCESSING`, `SUCCESS`, `FAILURE`, `SKIPPED`.",
            "type": "string"
          },
          "type": {
            "description": "Operation type. Allowed values: `REPORTING`, `INVOICING`.",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "in": "header",
        "name": "Ocp-Apim-Subscription-Key",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "title": "Fonoa E-invoicing",
    "version": "1.0.0"
  },
  "openapi": "3.0.0",
  "paths": {
    "/v1/transactions": {
      "get": {
        "description": "Used to search for transactions.",
        "parameters": [
          {
            "description": "Search by whether the transaction is a backfill",
            "in": "query",
            "name": "backfill",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "description": "Search by transaction country code.",
            "in": "query",
            "name": "country_code",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search by the input source of the transaction, e.g. `API`, `CSV`, `TAX_AUTHORITY`, `DIGITAL_EXCHANGE`",
            "in": "query",
            "name": "data_source",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "A flag to be used in a migration phase. It signals in which format amounts should be parsed. If true amounts are parsed as decimals, if false amounts are parsed as an integer representing the minor currency unit.",
            "in": "query",
            "name": "decimal_amounts",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "description": "Search by the Transaction direction, can either be inbound (RECEIVED) or outbound (SENT)",
            "in": "query",
            "name": "direction",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search by specific error types",
            "in": "query",
            "name": "error_types",
            "schema": {
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          },
          {
            "description": "Define page size - default 25",
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Define the next cursor to be fetched",
            "in": "query",
            "name": "next_cursor",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search by internal operation unique identifier.",
            "in": "query",
            "name": "operation_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search for records where the transaction was reported after a given RFC3339 date",
            "in": "query",
            "name": "reporting_date_from",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search for records where the transaction was reported before a given RFC3339 date",
            "in": "query",
            "name": "reporting_date_to",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Order search results by a given field",
            "in": "query",
            "name": "sort_by",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Define sort order - default ascending",
            "in": "query",
            "name": "sort_order",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search by company using Fonoa unique identifier.",
            "in": "query",
            "name": "supplier_company_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search by company name.",
            "in": "query",
            "name": "supplier_company_name",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search for records where the transaction was executed after a given RFC3339 date",
            "in": "query",
            "name": "transaction_date_from",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search for records where the transaction was executed before a given RFC3339 date",
            "in": "query",
            "name": "transaction_date_to",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search by external transaction unique identifier(s).",
            "in": "query",
            "name": "transaction_id",
            "schema": {
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          },
          {
            "description": "Search by transaction number(s).",
            "in": "query",
            "name": "transaction_number",
            "schema": {
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          },
          {
            "description": "Search by transactions that references the given fonoa id.",
            "in": "query",
            "name": "transaction_reference_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search by the effect the document has, either debiting or crediting",
            "in": "query",
            "name": "transaction_scenario",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search by Transaction status.",
            "in": "query",
            "name": "transaction_status",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search by a single transaction type or multiple transaction types",
            "in": "query",
            "name": "transaction_type",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search for records updated at or after a given RFC3339 date",
            "in": "query",
            "name": "updated_at_from",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search for records updated at or before a given RFC3339 date",
            "in": "query",
            "name": "updated_at_to",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search by workflow operations as a comma-separated string, e.g. `DOCUMENT_GENERATION,TA_NOTIFICATION`.",
            "in": "query",
            "name": "workflow_operations",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search by Transaction workflow status.",
            "in": "query",
            "name": "workflow_status",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchTransactionsResponse"
                }
              }
            },
            "description": "Ok - transactions for the provided search criteria were returned."
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OperationResultResponse"
                }
              }
            },
            "description": "Bad customer request - invalid search parameters."
          },
          "401": {
            "description": "Authentication failed - missing or incorrect subscription key"
          },
          "429": {
            "description": "Too many requests were sent for a short period of time. Try again a bit later."
          },
          "5XX": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OperationResultResponse"
                }
              }
            },
            "description": "Internal server error. Its not you, its us! We are experiencing a rare and unexpected system disruption. Retry again later. The message field of the response will contain more information for the cause. Feel free to contact us."
          }
        },
        "summary": "Get a list of transactions",
        "tags": [
          "Transactions"
        ]
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "Transactions"
    }
  ]
}
```