GuidesAPI Reference
Guides

Schedule Report

Use this request to schedule a report.

Suggest Edits

You have 2 options for running this report. Each has its own input parameters and output fields:

  • Option 1: Vertex for Marketplaces users can use this report to schedule a general audit report.
  • Option 2: Standalone Vertex Validator users can use it to create a report about Tax ID validation. The input parameters differ for each option.

📘

Note

This request schedules a single report. The results are returned by the List Reports request.

To schedule a report, use a POST method and the following URL:

https://{service_uri}/api/v3/reports

where {service_uri} is the URL of the service.

For example:

https://reporting-api.marketplace.taxamo.com/api/v3/reports

Details

DetailValue
Endpoint/api/v3/reports
MethodPOST

Input Parameters

The 2 available options have different input parameters to serve their different use cases:

Option 1

ParameterTypePatternMaxMinRequiredDescription
report-typeStringn/an/an/aYesYou must use Audit.
formatStringn/an/an/aNoYou must use csv for an uncompressed file or csv.gz for a compressed file.
product-classesString or Null^(S|P|D)\*n/an/aNoSpecify P for Physical goods. If you do not specify a value, all Product Classes are returned.
end-dateString^\\d{4}-\\d{2}-\\d{2}$n/an/aYesSpecify the end date.
fx-sourceStringn/an/an/aYesSelect a source for currency conversions. See Currency Conversion Source Values.
tax-country-subdivision-codeString or Null\\w\\w-\\w\\w55NoSpecify a country subdivision. For example, US-FL for Florida.
tax-country-codeString or Nulln/a22NoSpecify a country code if you want the report to be for a specific country.
currency-codeString or Null^\\w{3}$33NoSpecify a currency. All amounts will be converted into this currency in the report. If you do not, the default currency for the country is used.
fx-date-typeStringn/an/an/aYesThis controls the date that will be used for any currency conversions. Select one of day, prev-day, or end. This is required if you specify a value for currency-code.
tax-region-keyString or Null^[A-Z]{2}$22NoYou can use this to filter for specific values. For example, if you specify EU, only EU transactions will be included in the report.
report-scopeString or Nulln/an/an/aNoSpecify the scope of the report. Values are explained in the Report Scope Values topic.
transaction-typeString or Nulln/an/an/aNoChoose either Sale for sales or Refund for refunds. If you choose neither, both are included in the report.
start-dateString^\\d{4}-\\d{2}-\\d{2}$n/an/aYesSpecify the date the report will start from.
fx-date-fieldString or Nulln/an/an/aNoChoose tax-timestamp to use the Tax timestamp for the FX date. Choose invoice-timestamp to use the invoice timestamp for the FX date. If no value is specified, the tax-timestamp is used.

Option 2

ParameterTypePatternMaxMinRequiredDescription
start-dateString^\\d{4}-\\d{2}-\\d{2}$n/an/aYesSpecify when the period covered by the report starts.
end-dateString^\\d{4}-\\d{2}-\\d{2}$n/an/aYesSpecify when the period covered by the report ends.
tax-idsString and Nulln/an/a1NoYou can specify a list of Tax IDs to return in the report.
region-keysString and Null^[A-Z]{2}$22NoSpecify a region. For example, EU. The report results will be filtered for this region. You can also specify Unknown if you do not know the region. If you specify no value,
validation-statusesStringn/an/an/aNoSee Validation Status Values
result-changedBoolean and Nulltrue or falsen/an/aNoIf set to true, only Tax IDs where the validation result changed are included.

Examples

Request

Option 1

The following is an example request for option 1:

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"
  }
}
'

Option 2

The following is an example request for option 2:

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
  }
}
'

Response

Option 1

The following is a response to a request using option 1:

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

Option 2

The following is a response to a request using option 2:

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
  }
}
'

Updated about 1 month ago