Batches

Batch mass VAT number validations for due dates. You can add VAT numbers in bulk or append VAT numbers incrementally to your existing batch process, then start it whenever required.

You can use batches to perform VAT number validations in bulk. Once you start the validation process, Vatstack will automatically create validation objects for each query you had added to the batch. Batches can be used and maintained flexibly according to your business requirements:

Start the validation process immediately:

  • Create a new batch object by providing the name and an array of queries in the request body, and take note of the unique identifier id obtained from the response.

  • Change the batch’s status to scheduled using the id obtained in the previous step. This will start the validation process by putting the batch on a queue.

Start the validation process in the future:

  • Create a new batch object by providing only a name in the request body, and take note of the unique identifier id obtained in the response. You can also query a list of pending batches later on if you don’t take note of the id.

  • Incrementally append VAT numbers that you want to validate on a deadline. For example you can append the VAT numbers of new users.

  • Once you have collected all VAT numbers which you want to batch process, change the batch’s status to scheduled using the id obtained in the first step. This will start the validation process by putting the batch on a queue.

Batch VAT validations using the dashboard:

You don’t have to use the API if you don’t want to implement batches programmatically. Our dashboard lets you upload CSV files conveniently and start the validation process with an easy-to-use interface. All validation results can be downloaded as CSV anytime.

The Batch Object

Key

Description

id

Unique identifier for the object.

created

ISO date at which the object was created.

name

Descriptive name of the object.

queries

List of all queries in the order of your input.

queries_ignored

List of all queries which are of invalid format. Ignored queries are automatically identified upon your input. Its items will not be validated.

scheduled

ISO date at which the object status was changed to scheduled. Defaults to null while the status is pending.

status

Status of the validation process. Batches are initialized with the pending status. You can change the status to scheduled upon which the validation process is scheduled for processing. Once picked up, the status changes to processing. In rare cases, the status can change to error which requires user amendments. If all validations succeeded, the status finally changes to completed.

succeeded_count

The number of validations where valid is true or false. It’s an indicator for how far the batch has progressed.

updated

ISO date at which the object was updated.

validations

List of the first 20 validation objects in the order of queries. If an id is shown in the object, it was created for the batch and you can retrieve it individually. See validation object for reference.

post
Create a batch

https://api.vatstack.com/v1/batches
Creates a batch object.
Request
Response
Request
Body Parameters
name
required
string
Descriptive name of the batch object. Give it any name you like to serve for your reference.
queries
optional
array
List of VAT IDs to be queried. Should be an array of strings.
Response
201: Created
Batch object successfully created (example includes one valid query and one invalid query).
{
"id": "5dae0611273f2a47db1acd27",
"name": "Validations for November",
"queries": [],
"queries_ignored": [],
"scheduled": null,
"status": "pending",
"succeeded_count": 0,
"validations": {
"has_more": false,
"validations": [],
"validations_count": 0
},
"created": "2019-10-21T19:25:05.501Z",
"updated": "2019-10-21T19:25:05.501Z"
}

The queries array can be left empty if you merely want to create a new batch object and to obtain its unique identifier id for manipulation later on.

Batches will not process until you explicitly change their status field to scheduled. Use the PUT method to change a status. This gives you the opportunity to add more queries over time and to start the batch validation process once a deadline is due.

get
List all batches

https://api.vatstack.com/v1/batches
Retrieves all batch objects in order of creation, with the latest appearing highest.
Request
Response
Request
Query Parameters
limit
optional
number
A limit on the number of object to be returned. Limit can be 1 to 100, and the default is 20.
page
optional
number
Integer for the current page.
status
optional
string
Show only objects with the given status.
Response
200: OK
Schedule objects successfully retrieved.
{
"has_more": false,
"schedules_count": 5,
"schedules": [
{
"id": "5dae0611273f2a47db1acd27",
"name": "Validations for November",
"queries": [
"DE811128135",
"INVALIDNUMBER"
],
"queries_count": 2,
"queries_ignored": [
"INVALIDNUMBER"
],
"queries_ignored_count": 1,
"scheduled": null,
"status": "pending",
"succeeded_count": 1,
"validations": {
"has_more": false,
"validations": [
{
"query": "DE811128135",
"valid": null,
"valid_format": true
},
...
],
"validations_count": 2
},
"created": "2019-10-21T19:25:05.501Z",
"updated": "2019-10-21T19:43:12.348Z"
},
...
]
}

get
Retrieve a batch

https://api.vatstack.com/v1/batches/:id
Retrieves a batch object.
Request
Response
Request
Path Parameters
id
required
string
Identifier of the batch object to be retrieved.
Response
200: OK
Schedule object successfully retrieved.
{
"id": "5dae0611273f2a47db1acd27",
"name": "Validations for November",
"queries": [
"DE811128135",
"INVALIDNUMBER"
],
"queries_count": 2,
"queries_ignored": [
"INVALIDNUMBER"
],
"queries_ignored_count": 1,
"scheduled": null,
"status": "pending",
"succeeded_count": 1,
"validations": {
"has_more": false,
"validations": [
{
"query": "DE811128135",
"valid": null,
"valid_format": true
},
...
],
"validations_count": 2
},
"created": "2019-10-21T19:25:05.501Z",
"updated": "2019-10-21T19:43:12.348Z"
}

put
Update a batch

https://api.vatstack.com/v1/batches/:id
Updates a batch object.
Request
Response
Request
Path Parameters
id
required
string
Identifier of the batch object to be updated.
Body Parameters
mode
optional
string
Either append to append an array of queries to the existing array of queries, or replace to empty the existing array of queries prior to adding. Defaults to append.
name
optional
string
Descriptive name of the batch object.
queries
optional
array
List of VAT IDs to be added while considering the mode.
status
optional
string
Set it to scheduled once you want to schedule the validation process with the queries provided. It’s possible to add queries and change the status in one go.
Response
200: OK
Schedule object successfully updated.
{
"id": "5dae0611273f2a47db1acd27",
"name": "Validations for November",
"queries": [
"DE811128135",
"INVALIDNUMBER"
],
"queries_count": 2,
"queries_ignored": [
"INVALIDNUMBER"
],
"queries_ignored_count": 1,
"scheduled": "2019-10-22T12:24:42.325Z",
"status": "scheduled",
"succeeded_count": 1,
"validations": {
"has_more": false,
"validations": [
{
"query": "DE811128135",
"valid": null,
"valid_format": true
},
...
],
"validations_count": 2
},
"created": "2019-10-21T19:25:05.501Z",
"updated": "2019-10-22T12:24:42.843Z"
}

This method is especially useful if you want to gradually append new VAT numbers over time, for example, towards an upcoming submission deadline for your VAT MOSS return. Simply add a queries array to your request body to add new VAT numbers to the batch.

Duplicates will be purged and invalid VAT numbers ignored automatically for you. You don’t have to check whether or not a VAT number already exists in the batch.

Once you are ready to start the validation process, change the status to scheduled. Depending on the availability of various government services, this process can take several hours. It is recommended that you start the batch several days prior to a deadline. In most cases, all validations in a batch should succeed immediately or within a few hours.

delete
Delete a batch

https://api.vatstack.com/v1/batch/:id
Deletes a batch object.
Request
Response
Request
Path Parameters
id
required
string
Identifier of the batch object to be deleted.
Response
200: OK
Schedule object successfully deleted.
{
"id": "5dae0611273f2a47db1acd27",
"deleted": true
}