{
  "openapi": "3.0.1",
  "info": {
    "title": "VIES VAT Validator – Bulk EU VAT Number Check",
    "description": "Bulk VAT number validation through VIES for invoicing software, accountants and B2B webshops. Tells valid, invalid and \"member state down\" apart (never a false invalid), returns the registered name and the consultation number for reverse charge, and finds VAT numbers by company name.",
    "version": "0.1",
    "x-build-id": "b1W8NYWHXtwzpslXh"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/lwsdjfls~vies-vat-validator/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-lwsdjfls-vies-vat-validator",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/lwsdjfls~vies-vat-validator/runs": {
      "post": {
        "operationId": "runs-sync-lwsdjfls-vies-vat-validator",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/lwsdjfls~vies-vat-validator/run-sync": {
      "post": {
        "operationId": "run-sync-lwsdjfls-vies-vat-validator",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "vatNumbers": {
            "title": "VAT numbers",
            "maxItems": 50000,
            "type": "array",
            "description": "One per line, with country prefix (NL810433941B01, BE 0403.170.701, ATU12345678). Spaces, dots and dashes are fine; GR is read as EL. Numbers without a prefix use the default country below. One run checks up to 15,000 numbers and company names with the default 1 GB of memory and 55,000 with 4 GB; results kept from earlier runs of the task or state key take memory too. What does not fit is not checked or charged: the run ends as partial and the log says why. When nothing fits, the run fails, or deletes results due for deletion to make room for the next run. A run also keeps up to 0.1 s per record before its timeout to deliver them, and checks only what it can deliver: give a large input a longer timeout.",
            "items": {
              "type": "string",
              "maxLength": 100
            },
            "default": []
          },
          "companyNames": {
            "title": "Company names (find the VAT number)",
            "maxItems": 5000,
            "type": "array",
            "description": "One per line as \"Company name; country code\", for example \"Coolblue; NL\". Candidates come from the Peppol Directory (all countries) and, for France, the French company register; each is confirmed in VIES. French sole traders are not searched by name.",
            "items": {
              "type": "string",
              "maxLength": 300
            },
            "default": []
          },
          "defaultCountry": {
            "title": "Default country",
            "enum": [
              "AT",
              "BE",
              "BG",
              "CY",
              "CZ",
              "DE",
              "DK",
              "EE",
              "EL",
              "ES",
              "FI",
              "FR",
              "HR",
              "HU",
              "IE",
              "IT",
              "LT",
              "LU",
              "LV",
              "MT",
              "NL",
              "PL",
              "PT",
              "RO",
              "SE",
              "SI",
              "SK",
              "XI"
            ],
            "type": "string",
            "description": "Country for VAT numbers without prefix and company names without country code."
          },
          "requesterVatNumber": {
            "title": "Your VAT number (for consultation numbers)",
            "maxLength": 40,
            "type": "string",
            "description": "Your own EU VAT number. VIES then issues a consultation number per check: proof that you verified your customer's number on that date, which tax authorities accept for reverse-charge invoices. Leave empty to validate without consultation numbers."
          },
          "maxWaitMinutes": {
            "title": "Wait for an unavailable member state (minutes)",
            "minimum": 1,
            "maximum": 60,
            "type": "integer",
            "description": "How long a member state may keep failing (down, time-outs, too many requests) before its remaining numbers are reported as unavailable; at most until the run stops checking before its timeout. Waiting is free: unavailable numbers are never charged, and with \"Retry unavailable numbers in later runs\" a saved task picks them up next run. Raise it to 5 or more when you run once a day and want the answer in that run rather than the next.",
            "default": 1
          },
          "retryUnavailableInLaterRuns": {
            "title": "Check unavailable numbers again in the next runs",
            "type": "boolean",
            "description": "For saved tasks (or runs with a state key): numbers and companies VIES could not check are checked again in the following runs, even if they are no longer in the input, and delivered once VIES answers.",
            "default": true
          },
          "retryForDays": {
            "title": "Keep retrying for (days)",
            "minimum": 1,
            "maximum": 30,
            "type": "integer",
            "description": "Numbers that stay unavailable are retried for this many days after the first failed check.",
            "default": 7
          },
          "minMatchScore": {
            "title": "Minimum name similarity (%)",
            "minimum": 50,
            "maximum": 100,
            "type": "integer",
            "description": "How similar the registered name must be to the name you gave. Legal forms, punctuation and case are ignored; 100 means identical.",
            "default": 80
          },
          "maxCandidatesPerCompany": {
            "title": "Candidates checked per company",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "How many similar companies are validated in VIES per name (best names first).",
            "default": 3
          },
          "maxChecksPerRun": {
            "title": "Maximum charged checks per run",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Caps the charged validations and matches in one run. Inputs above the cap are not checked: a number with an earlier result keeps it (marked fromEarlierRun), others are listed as skipped.",
            "default": 10000
          },
          "maxConcurrency": {
            "title": "Parallel checks",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Checks running at the same time. Per member state at most 3, and fewer when it reports too many requests.",
            "default": 6
          },
          "useTestService": {
            "title": "Use the VIES test service",
            "type": "boolean",
            "description": "For integration tests, free of charge: VIES answers number 100 as valid, 200 as invalid, 300 SERVICE_UNAVAILABLE, 301 MS_UNAVAILABLE, 302 TIMEOUT, 400 VAT_BLOCKED, 600 MS_MAX_CONCURRENT_REQ (use with a default country). Company names are not matched.",
            "default": false
          },
          "webhookUrl": {
            "title": "Webhook URL",
            "type": "string",
            "description": "Receives a POST with the new and changed results after each run (for example a number that is no longer valid)."
          },
          "stateKey": {
            "title": "State key",
            "type": "string",
            "description": "Keeps results and retries separate for runs outside a saved task (for example per customer file). Tasks use their own state automatically; all runs without a task or state key share one. Runs with the same state take turns: a run that starts while another is working waits for it, at most 10 minutes, and fails without checks or charges if that run is still working then. Stored encrypted, because it often names a customer."
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Not needed normally. Use a proxy only when VIES answers IP_BLOCKED.",
            "default": {
              "useApifyProxy": false
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}