Salesforce VAT Validation

Salesforce stores VAT and tax ID numbers as plain text on Account records. There is no native validation. 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 Vatly REST API. You will also learn how to write the validated company name back to Account records.

The integration pattern

Vatly 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 Vatly → 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 Vatly:

• Go to Setup → Named Credentials → External Credentials. Create a new External Credential with the authentication protocol set to "Custom".
• Add a Principal. In the authentication parameters, add a header named Authorization with the value Bearer vtly_live_your_api_key.
• Create a Named Credential that references this External Credential. Set the base URL to https://api.vatly.dev.
• 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 Vatly 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:Vatly_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

Vatly 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 vtly_test_ instead of vtly_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 Vatly account →

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