README

Official PHP SDK for the BDM DataFinder API.

Installation

composer require bdm/datafinder

Configuration

Publish the config file:

php artisan vendor:publish --tag=datafinder-config

Add your API key to .env:

BDM_DATAFINDER_API_KEY=bdm_pro_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
BDM_DATAFINDER_BASE_URL=https://api.bdmdatafinder.com/api/v1

Usage

Find a Business

use BDM\DataFinder\Facades\DataFinder;

$result = DataFinder::business()->find('ERA Real Estate', location: 'Cape Town');

echo $result->topName();       // ERA Real Estate
echo $result->topWebsite();    // https://www.era.co.za
echo $result->topConfidence(); // 0.48
echo $result->topBand();       // weak

Find Similar / Competitors

$result = DataFinder::business()->findSimilar('ERA Real Estate', location: 'Cape Town');

foreach ($result->results() as $competitor) {
    echo $competitor['name'] . ' — ' . $competitor['address'];
}

Extract Products / Services

$result = DataFinder::business()->findProducts('KPMG South Africa', website: 'https://www.kpmg.com/za');

foreach ($result->offerings() as $offering) {
    echo $offering['name']; // Audit, Advisory, etc.
}

Validate a Business (KYC)

$result = DataFinder::validation()->business(
    name:    'ERA Real Estate',
    website: 'https://www.era.co.za',
    phone:   '+27813612603',
    address: '20 London Rd, Sea Point, Cape Town',
);

echo $result->score();    // 0.882
echo $result->verdict();  // pass
echo $result->isPassed(); // true

Bulk Enrichment

$job = DataFinder::bulk()->enrich([
    ['name' => 'ERA Real Estate',   'location' => 'Cape Town',     'reference' => 'lead_001'],
    ['name' => 'KPMG',              'location' => 'Johannesburg',  'reference' => 'lead_002'],
    ['name' => 'Woolworths',        'location' => 'Cape Town',     'reference' => 'lead_003'],
]);

echo $job->jobId(); // bulk_xxxxx

// Poll for results
$status = DataFinder::bulk()->status($job->jobId());
echo $status->progress() . '%'; // 100%

// Or wait for completion (small batches only)
$status = DataFinder::bulk()->enrichAndWait([
    ['name' => 'ERA Real Estate', 'location' => 'Cape Town'],
]);

foreach ($status->results() as $result) {
    echo $result['result']['name'];
}

Reverse Lookups

// Domain to company profile
$result = DataFinder::business()->findByEmailDomain('info@era.co.za');
echo $result->name();        // ERA Group South Africa
echo $result->description(); // ERA Real Estate has been...

// Find businesses at an address
$result = DataFinder::business()->findByAddress('19 Edison Way, Century City, Cape Town');
foreach ($result->businesses() as $business) {
    echo $business['name'];
}

// VAT number lookup
$result = DataFinder::business()->findByVatNumber('4360189102', 'ZA');
echo $result->isVerified(); // true
echo $result->format();     // ZA_VAT

// Person to businesses
$result = DataFinder::business()->findByPerson('Johann Rupert', location: 'South Africa');
foreach ($result->associations() as $assoc) {
    echo $assoc['business']['name'];
}

Error Handling

use BDM\DataFinder\Exceptions\AuthenticationException;
use BDM\DataFinder\Exceptions\RateLimitException;
use BDM\DataFinder\Exceptions\DataFinderException;

try {
    $result = DataFinder::business()->find('ERA Real Estate', location: 'Cape Town');
} catch (AuthenticationException $e) {
    // Invalid API key
} catch (RateLimitException $e) {
    // Rate limited — retry after $e->retryAfter seconds
    sleep($e->retryAfter);
} catch (DataFinderException $e) {
    // General API error
}

Without Laravel (Plain PHP)

use BDM\DataFinder\DataFinderClient;

$client = new DataFinderClient(
    apiKey:  'bdm_pro_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    baseUrl: 'https://api.bdmdatafinder.com/api/v1',
);

$result = $client->business()->find('ERA Real Estate', location: 'Cape Town');

---

Once all files are created your structure should look like:

bdm-datafinder-sdk/ ├── composer.json ├── README.md ├── config/ │ └── datafinder.php └── src/ ├── DataFinderClient.php ├── DataFinderServiceProvider.php ├── Facades/ │ └── DataFinder.php ├── Resources/ │ ├── BusinessResource.php │ ├── BulkResource.php │ └── ValidationResource.php ├── Responses/ │ ├── BaseResponse.php │ ├── BusinessResponse.php │ ├── BulkJobResponse.php │ ├── BulkStatusResponse.php │ ├── TypeSearchResponse.php │ ├── ProductsResponse.php │ ├── EmployeesResponse.php │ ├── SimilarResponse.php │ ├── PhoneResponse.php │ ├── EmailDomainResponse.php │ ├── PersonResponse.php │ ├── AddressResponse.php │ ├── VatResponse.php │ └── ValidationResponse.php └── Exceptions/ ├── DataFinderException.php ├── AuthenticationException.php └── RateLimitException.php