Skip to main content
Invopop’s Lookup app checks the tax ID of a party against the official register that issues it. Add its Validate Tax IDs step to an invoice or party workflow to make sure that the tax ID exists before you sign, send or register a document, and to write the party’s legal name into the document. Lookup keeps recent register answers in a cache, so repeated checks of the same tax ID are faster and do not call the register again. The step decides how old a cached answer may be, or asks the register every time.

​
How it works

Each Validate Tax IDs step checks one party:
  • In an invoice workflow, the step checks the customer or the supplier, as configured.
  • In a party workflow, the step checks the party document itself.
The step checks the party’s tax_id. Entries in identities are not checked. A tax ID that no register covers is skipped and costs nothing. The step asks the register that issues the tax ID:
  • Spanish tax IDs go to the AEAT census. See Spanish tax IDs.
  • French tax IDs go to the DGFiP. See French tax IDs.
  • Other EU VAT numbers go to VIES.

​
Set up the step

1

Enable the Lookup app

In the Console, open the apps directory by clicking the icon next to Apps in the sidebar. Find Lookup in the list of available apps and enable it in your workspace.
2

Add the step to a workflow

Open an invoice or party workflow and add the Validate Tax IDs step. Place it before the steps that need a valid tax ID, such as Sign envelope, or a step that sends the invoice to a tax authority or network.
3

Configure the step

Choose the party to check, how old a cached answer may be, and whether the step corrects the party. See Step configuration below.

Ask your agent to add tax ID validation to one of your workflows.

Open in Cursor

​
Step configuration

In the workflow JSON, these fields are party, max_age and correct:

​
Handle the results

The step returns a status and a code. After OK or SKIP, the workflow continues with the next step. After KO, the workflow stops and runs its rescue steps, unless an exception handles that code. Add conditions and exceptions only for the codes that your process must handle in a special way.

​
The tax ID is valid

The step returns OK:
  • found: the register confirms the tax ID, and the names match.
  • found-name-mismatch: the register confirms the tax ID, but the name in the document is different.
  • found-inactive: the register confirms the tax ID, but holds the party as inactive.
  • found-dissolved: the register confirms the tax ID, but holds the party as dissolved.
  • found-not-vat-registered: the tax ID belongs to an active business that is not registered for VAT, such as a French micro-entrepreneur under the franchise en base. The business exists, but has no VAT number.
found-inactive, found-dissolved and found-not-vat-registered are warnings: the workflow continues, and the correction still runs.

​
The tax ID is not valid

The step returns KO:
  • not-found: the register does not hold the tax ID. Check the tax ID with your customer. To reject these invoices automatically, see Stop on an unregistered customer.
  • revoked: the register identifies the party, but the tax authority revoked the tax ID, so it has no legal effect. Ask your customer for a valid tax ID.
  • input: the register rejects the tax ID as badly formed, for example a code with the wrong length. Correct the tax ID in the document and run the job again. The step also returns this code when the party lacks data that the register needs, for example AEAT needs the name of a natural person to check a DNI or NIE. Add the name to the party and run the job again.

​
The step is skipped

The step returns SKIP, and the workflow continues:
  • no-identifiers: the party has no tax ID, as is common for a consumer. To handle these documents differently, add a condition with the status Any on this code.
  • missing-party: the invoice has no party to check, such as a simplified invoice without a customer.
  • not-supported: no register covers the tax ID.

​
The register does not answer

The step returns ERR with the code upstream, and Invopop retries it automatically. You do not need to do anything. The step never uses an older cached answer in place of the register’s answer.

​
The step cannot run

The step returns KO when its setup is wrong:
  • not-enrolled: the Lookup app is not enabled in the workspace. Enable it in the Console.
  • not-configured: the app is not set up correctly. Contact support.
  • silo-entry: the document of the job cannot be found.
  • bad-document: the document cannot be read.
  • bad-config: the step configuration cannot be read. Open the step and save its configuration again.
  • invalid-party: the step selects an unknown party. Select the customer or the supplier.
  • unsupported-schema: the document is not an invoice or a party. Use the step in an invoice or party workflow.

​
Correction

With Correct the party on, a check that passes writes the register’s data into the document:
  • Name: the registered name replaces the document’s name whenever the two differ, including a difference in case only. The registered spelling is the legal one.
  • Address: a structured address from the register becomes the party’s first address, and the other addresses stay.
  • Tax ID: never changed.
Nothing is written when the check does not pass, when the register gives no name, or when the document is already signed. To correct a document and then sign it, place Validate Tax IDs before Sign envelope. The correction never changes the result code or the message. A corrected document still returns found, found-name-mismatch or its warning code.

​
Spanish tax IDs

Lookup checks Spanish tax IDs (NIF) in the census of AEAT, the Spanish tax agency. AEAT holds every NIF, not only the NIFs registered for intra-EU trade, and gives the registered name.
  • Companies are identified by the NIF alone. A wrong or empty name still gives a valid answer with the registered name.
  • Natural persons, such as self-employed workers (autónomos), have a DNI or NIE as their NIF. AEAT needs the person’s name to check it. A name that AEAT accepts returns found. A name that belongs to another person returns not-found.
  • Revoked NIFs return revoked. Deregistered NIFs return found-inactive.

​
French tax IDs

Lookup checks French VAT numbers with the DGFiP, the French tax administration, which publishes every active French VAT number.
  • Businesses without a VAT number, such as micro-entrepreneurs under the franchise en base, use their SIREN as tax ID. When the SIREN belongs to an active business in Sirene, the French business register, the step returns found-not-vat-registered.
  • Name and address: the registered name and the structured address of the head office come from Sirene. A sole trader gets the person’s name. With Correct the party on, both are written into the document.
  • Closed companies return found-inactive while their VAT number is active, and not-found otherwise.

​
Workflow examples

​
Validate the invoice customer

Validate the customer’s tax ID, write the registered name into the invoice, and sign it.

​
Stop on an unregistered customer

An exception on the not-found code sets the state to rejected and stops the job, so the invoice is never signed. Every other invoice is signed as usual.

​
Validate a party

Validate a party’s tax ID and write the registered name into the party, for example before you register it with a tax authority.

Participate in our community

Ask and answer questions about the Lookup app →