DEV Community

VOYGR
VOYGR

Posted on

How to verify a business is real and operating at its address

#kyb #api #fintech #tutorial

Before you onboard a merchant, approve a loan or send a sales rep, you want to know two things about a business: that it really exists at the address it gave you, and that it's still operating. A registry record answers neither. A company can be registered at a mailbox, and a shop can close while its registration stays active for years.

What to check

  • Does a place by that name exist at that address? Look for a storefront, a map listing, a website or social profile that gives the same address, reviews tied to the location.
  • Is it open today? Recent hours, recent reviews or posts, a working phone line. A closure notice, relocation notice or disconnected number points the other way.
  • Who runs it? Owner and key people, if your process needs them.

By hand, that's a few minutes per business.

One call: exists, and open or closed

The VOYGR Validate API takes a business name and full address (coordinates optional) and returns two separate answers.

curl https://api.voygr.tech/v1/validate \
  --request POST \
  --header "X-API-Key: $VOYGR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "poi_name": "Example Bakery",
    "address": "123 Example Street, San Francisco, CA 94103, US",
    "latitude": 37.7749,
    "longitude": -122.4194
  }'
Enter fullscreen mode Exit fullscreen mode

existence_confidence (0.0 to 1.0) scores whether a matching place has existed at that location. It doesn't tell you whether the business is open today: a closed business can still score high.

For the operating decision, read operational_status.status: open, closed, unknown or not_exists. Treat unknown as "check again". not_exists means we didn't judge the place to exist, so there's no open or closed call. For closed results, closure_reason names the kind of evidence behind it, and closure_confidence lets you rank places within one status.

Thousands at once

A validation job takes 1 to 10,000 records and returns results asynchronously. Each item in pois is the same body as a single request:

curl https://api.voygr.tech/v1/jobs/validate \
  --request POST \
  --header "X-API-Key: $VOYGR_API_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{"pois": [
    {"id": "bakery-001", "poi_name": "Example Bakery", "address": "123 Example Street", "latitude": 37.7749, "longitude": -122.4194},
    {"id": "cafe-002", "poi_name": "Example Cafe", "address": "456 Sample Avenue", "latitude": 37.7755, "longitude": -122.4183}
  ]}'
Enter fullscreen mode Exit fullscreen mode

You get a batch_id back and poll it. If the submission response gets lost, retry with the same Idempotency-Key and body instead of sending a new job.

Owners, contacts and the ones you still doubt

The Enrich API adds phone, website, socials, opening hours, and owners and key people, each with a confidence and an as_of date.

For the records that stay unknown, PlaceCall phones the business and asks. That's how we settled the disputed cases in our Google Maps closed-business study: of 30 places where the map listing disagreed with us, independent sources and phone calls showed 23 were really closed.

Keys come with 2.5K free credits, no card: api.voygr.tech/checkout.

Top comments (0)