Salesforce VAT Validation

Salesforce has no standard VAT number field; teams store VAT numbers in custom text fields on Account records, and nothing validates them. Sales reps enter whatever they have, and the data goes unverified into invoices, opportunity records, and ERP syncs.

This guide shows how to validate VAT numbers inside Salesforce using Apex HTTP callouts, Named Credentials, and the Avatcado REST API. You will also learn how to write the validated company name back to Account records.

The integration pattern

Avatcado is a REST API that accepts a VAT number and returns the validation status, the registered company name, and the country code. In Salesforce, you call it via an Apex HTTP callout. You can trigger the callout from an Apex trigger, a Flow action, or a custom button on the Account page.

The flow is: Account record is created or updated with a VAT number → Apex callout to Avatcado → parse the response → update Account fields with the result.

Setting up a Named Credential

Named Credentials store the endpoint URL and authentication details so you do not hardcode API keys in Apex. Salesforce injects the credentials automatically when your code references the Named Credential.

To set up a Named Credential for Avatcado:

• Go to Setup → Named Credentials → External Credentials. Create a new External Credential with the authentication protocol set to "Custom".
• Add a Principal. In the principal's authentication parameters, store your API key as a parameter named ApiKey.
• Create a Named Credential that references this External Credential. Set the base URL to https://api.avatcado.com.
• On the Named Credential, add a Custom Header named Authorization with the formula {!'Bearer ' & $Credential.Avatcado.ApiKey}. Uncheck "Generate Authorization Header" and check "Allow Formulas in HTTP Header".
• Create a Permission Set that grants access to the External Credential principal. Assign it to the users or integration user that will run the callout.

Apex callout example

The following Apex class makes a GET request to the Avatcado validate endpoint and returns a parsed result. It uses the Named Credential so the Authorization header is injected automatically.

public class VatValidationService {

    public class VatResult {
        public Boolean valid;
        public String companyName;
        public String countryCode;
    }

    public static VatResult validate(String vatNumber) {
        HttpRequest req = new HttpRequest();
        req.setEndpoint(
            'callout:Avatcado_API/v1/validate?vat_number='
            + EncodingUtil.urlEncode(vatNumber, 'UTF-8')
        );
        req.setMethod('GET');
        req.setHeader('Accept', 'application/json');

        Http http = new Http();
        HttpResponse res = http.send(req);

        VatResult result = new VatResult();

        if (res.getStatusCode() == 200) {
            Map<String, Object> body = (Map<String, Object>)
                JSON.deserializeUntyped(res.getBody());
            Map<String, Object> data = (Map<String, Object>)
                body.get('data');
            result.valid = (Boolean) data.get('valid');
            result.countryCode = (String) data.get('country_code');

            Map<String, Object> company = (Map<String, Object>)
                data.get('company');
            if (company != null) {
                result.companyName = (String) company.get('name');
            }
        } else {
            result.valid = false;
        }

        return result;
    }
}

Writing the result back to Account

Once you have the validation result, update the Account record with custom fields. A common pattern uses two fields: a checkbox VAT_Validated__c and a text field Registered_Company_Name__c.

You can call the VatValidationService.validate() method from:

• An Apex trigger on Account (after insert or after update on the VAT number field). Be careful: Apex triggers cannot make synchronous callouts directly. Use a @future(callout=true) method or a Queueable to make the callout asynchronously.
• A Flow action. Annotate a wrapper method with @InvocableMethod so Flow can call it. This lets admins add VAT validation to any Flow without writing additional Apex.
• A custom button or Lightning action on the Account page, letting sales reps validate on demand.

Test mode

Avatcado has a test mode with magic VAT numbers so you can build and test in a Salesforce sandbox without hitting live government APIs. Use an API key prefixed with avat_test_ instead of avat_live_.

Magic numbers like DE111111111 always return valid, and DE000000000 always return invalid. No quota is consumed in test mode. See the documentation for the full list of test numbers.

Get started

Create a free Avatcado account →

Read the API documentation for the full endpoint reference. For a broader overview of CRM integration patterns, see the CRM validation guide.