This request creates and schedules a report in one of two ways, each with different parameters and outputs:

Vertex O Series Cloud Online Commerce—Use this report to create and schedule a general audit report.
Standalone Vertex Validator—Use this report to generate a tax number validation report with different parameters.

This request schedules a single report. Use the List Reports request to retrieve the results.

Details

Endpoint	Method
`/api/v3/reports`	POST

Request parameters

The report options support different use cases and therefore accept different sets of parameters. Choose the option that best matches your requirements and the transaction details you need to provide.

Online Commerce

Field	Type	Format	Max	Min	Required	Description
`report-type`	String	N/A	N/A	N/A	Yes	Specify `Audit` to generate an audit report.
`format`	String	N/A	N/A	N/A	No	Specify `csv` to generate an uncompressed report file or `csv.gz` to generate a compressed report file.
`product-classes`	String or Null	`^(S\|P\|D)\*`	N/A	N/A	No	Filter the report by product class. Specify `P` to include only physical goods. If omitted, the report includes all product classes.
`end-date`	String	`^\\d{4}-\\d{2}-\\d{2}$`	N/A	N/A	Yes	Specify the last date to include in the report.
`fx-source`	String	N/A	N/A	N/A	Yes	Specify the exchange rate source to use for currency conversions.
`tax-country-subdivision-code`	String or Null	`\\w\\w-\\w\\w`	5	5	No	Filter the report by country subdivision. For example, specify `US-FL` to include only transactions associated with Florida.
`tax-country-code`	String or Null	N/A	2	2	No	Filter the report by country. Specify a two-letter country code.
`currency-code`	String or Null	`^\\w{3}$`	3	3	No	Convert all monetary amounts in the report to the specified currency. If omitted, the report uses the country's default currency.
`fx-date-type`	String	N/A	N/A	N/A	Yes	Specify the date used to determine exchange rates for currency conversions. Valid values are `day`, `prev-day`, and `end`. Required when currency-code is specified.
`tax-region-key`	String or Null	`^[A-Z]{2}$`	2	2	No	Filter the report by tax region. For example, specify `EU` to include only transactions within the European Union.
`report-scope`	String or Null	N/A	N/A	N/A	No	Specify the scope of transactions to include in the report. See Report Scope Values.
`transaction-type`	String or Null	N/A	N/A	N/A	No	Filter the report by transaction type. Specify `Sale` to include sales transactions or `Refund` to include refund transactions. If omitted, both are included.
`start-date`	String	`^\\d{4}-\\d{2}-\\d{2}$`	N/A	N/A	Yes	Specify the first date to include in the report.
`fx-date-field`	String or Null	N/A	N/A	N/A	No	Specify which transaction date to use when determining the exchange rate. Use `tax-timestamp` to use the tax calculation timestamp or `invoice-timestamp` to use the invoice timestamp. If omitted, `tax-timestamp` is used.

Standalone Vertex Validator

Parameter	Type	Format	Max	Min	Required	Description
`start-date`	String	`^\\d{4}-\\d{2}-\\d{2}$`	N/A	N/A	Yes	Specify the first date in the reporting period.
`end-date`	String	`^\\d{4}-\\d{2}-\\d{2}$`	N/A	N/A	Yes	Specify the last date in the reporting period.
`tax-ids`	String and Null	n/a	N/A	1	No	Filter the report to include only the specified Tax IDs. You can provide one or more Tax IDs.
`region-keys`	String and Null	`^[A-Z]{2}$`	2	2	No	Filter the report by region. For example, specify `EU` to include only records associated with the European Union. Specify `Unknown` to include records where the region could not be determined. If omitted, all regions are included.
`validation-statuses`	String	n/a	N/A	N/A	No	Filter the report by validation status. See Validation Status Values.
`result-changed`	Boolean and Null	`true` or `false`	N/A	N/A	No	Specify `true` to include only Tax IDs whose validation result changed during the reporting period. If `false` or omitted, all matching records are included.

Sample requests

The following is a sample request for Vertex O Series Cloud Online Commerce:

curl --request POST \
     --url https://reporting-api.marketplace.taxamo.com/api/v3/reports \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "report-type": "Audit",
  "parameters": {
    "fx-source": "ECB",
    "fx-date-type": "day",
    "format": "csv",
    "product-classes": "p",
    "end-date": "20-07-2023",
    "tax-country-subdivision-code": "US-FL",
    "tax-country-code": "US",
    "currency-code": "USD",
    "tax-region-key": "US",
    "report-scope": "full",
    "transaction-type": "sale",
    "start-date": "01-01-2024",
    "fx-date-field": "tax-timestamp"
  }
}
'

The following is a sample request for Standalone Vertex Validator:

curl --request POST \
     --url https://reporting-api.marketplace.taxamo.com/api/v3/reports \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "report-type": "Tax-ID",
  "parameters": {
    "fx-source": "ECB",
    "fx-date-type": "day",
    "start-date": "01-01-2023",
    "end-date": "01-03-2023",
    "tax-ids": [
      "ABC23232, DEF430923"
    ],
    "region-keys": [
      "unknown",
      "EU"
    ],
    "validation-statuses": [
      "syntax-valid-full-valid-cache-not-used",
      "syntax-valid-full-invalid-cache-not-used"
    ],
    "result-changed": true
  }
}
'

Sample responses

The following is a sample response for Vertex O Series Cloud Online Commerce:

{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "Queued",
  "message": "string"
}

The following is a sample response for Standalone Vertex Validator:

curl --request POST \
     --url https://reporting-api.marketplace.taxamo.com/api/v3/reports \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "report-type": "Tax-ID",
  "parameters": {
    "fx-source": "ECB",
    "fx-date-type": "day",
    "start-date": "01-01-2023",
    "end-date": "01-03-2023",
    "tax-ids": [
      "ABC23232, DEF430923"
    ],
    "region-keys": [
      "unknown",
      "EU"
    ],
    "validation-statuses": [
      "syntax-valid-full-valid-cache-not-used",
      "syntax-valid-full-invalid-cache-not-used"
    ],
    "result-changed": true
  }
}
'