PHPackages                             stitch-digital/nametodomain-php-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. stitch-digital/nametodomain-php-sdk

ActiveLibrary[API Development](/categories/api)

stitch-digital/nametodomain-php-sdk
===================================

An SDK to easily work with the Name To Domain API

1.0.2(3mo ago)022MITPHPPHP ^8.2CI passing

Since Jan 16Pushed 3mo agoCompare

[ Source](https://github.com/stitch-digital/nametodomain-php-sdk)[ Packagist](https://packagist.org/packages/stitch-digital/nametodomain-php-sdk)[ Docs](https://github.com/stitch-digital/nametodomain-php-sdk)[ RSS](/packages/stitch-digital-nametodomain-php-sdk/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (6)Versions (5)Used By (0)

Name To Domain PHP SDK
======================

[](#name-to-domain-php-sdk)

[![Latest Version on Packagist](https://camo.githubusercontent.com/bf84684878764bd6b585f680b6ef3f8ae5cfc14e363ec12d402d742a476a6d9c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7374697463682d6469676974616c2f6e616d65746f646f6d61696e2d7068702d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/stitch-digital/nametodomain-php-sdk)[![Total Downloads](https://camo.githubusercontent.com/ff4bfc2b46f7f5b1a26f030dcf2a057ef45d9c6c51f5bb0eed9688288614618d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7374697463682d6469676974616c2f6e616d65746f646f6d61696e2d7068702d73646b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/stitch-digital/nametodomain-php-sdk)

This package is the official PHP SDK for the [Name To Domain](https://nametodomain.dev) API, built with [Saloon](https://docs.saloon.dev/) v3.

```
use NameToDomain\PhpSdk\NameToDomain;

// Single resolution (sync)
$result = NameToDomain::make($token)->resolve(
    company: 'Stitch Digital',
    country: 'GB'
);

// Batch enrichment (async)
$job = NameToDomain::make($token)->enrichBatch(
    items: [
        ['company' => 'Stripe', 'country' => 'US'],
        ['company' => 'Spotify', 'country' => 'SE'],
    ]
);
```

Behind the scenes, the SDK uses [Saloon](https://docs.saloon.dev) to make the HTTP requests.

Installation
------------

[](#installation)

```
composer require stitch-digital/nametodomain-php-sdk
```

To get started, we highly recommend reading the [Name To Domain API documentation](https://stitchdigital.gitbook.io/nametodomain).

Quick Start
-----------

[](#quick-start)

```
use NameToDomain\PhpSdk\NameToDomain;

// Single resolution (sync)
$result = NameToDomain::make($token)->resolve(
    company: 'Stitch Digital',
    country: 'GB'
);

// Batch enrichment (async)
$job = NameToDomain::make($token)->enrichBatch(
    items: [
        ['company' => 'Stripe', 'country' => 'US'],
        ['company' => 'Spotify', 'country' => 'SE'],
    ]
);

// Check batch job status and get results
$batchResult = NameToDomain::make($token)->enrichBatchJob(jobId: $job->id);

// Or iterate over all batch items (paginated)
$items = NameToDomain::make($token)->enrichBatchJobItems(jobId: $job->id)->collect()->all();
```

Usage
-----

[](#usage)

To authenticate, you'll need an API token. You can create one in the [API Dashboard at Name To Domain](https://nametodomain.dev/app/api-keys).

```
use NameToDomain\PhpSdk\NameToDomain;

$client = NameToDomain::make('your-api-token');
```

### Setting a timeout

[](#setting-a-timeout)

By default, the SDK waits 10 seconds for a response. Override via the constructor (`apiToken`, `baseUrl`, `requestTimeout`):

```
$client = new \NameToDomain\PhpSdk\NameToDomain(
    'your-api-token',
    'https://nametodomain.dev/api/v1',
    30
);
```

### Handling errors

[](#handling-errors)

The SDK will throw an exception if the API returns an error. For validation errors, the SDK will throw a `ValidationException`.

```
try {
    $client->resolve(company: '', country: 'US');
} catch (\NameToDomain\PhpSdk\Exceptions\ValidationException $exception) {
    $exception->getMessage(); // returns a string describing the errors

    $exception->getErrors(); // returns an array with all validation errors
    $exception->getErrorsForField('company'); // get errors for a specific field
}
```

For all other errors, the SDK will throw a `\NameToDomain\PhpSdk\Exceptions\NameToDomainException`.

```
try {
    $client->enrichJob(jobId: 'invalid-id');
} catch (\NameToDomain\PhpSdk\Exceptions\NameToDomainException $exception) {
    $exception->getMessage();
    $exception->response; // access the Saloon Response object for debugging
}
```

Resolve
-------

[](#resolve)

The resolve endpoint allows you to resolve a single company name to its official website domain with a confidence score.

### Resolve a company

[](#resolve-a-company)

You can use the `resolve` method to resolve a company name and country code to its domain.

```
$result = NameToDomain::make($token)->resolve(
    company: 'Stitch Digital',
    country: 'GB'
);
```

The response includes the original input and the resolution result. If no reliable match is found, the domain and confidence will be `null`.

### Resolve with emails

[](#resolve-with-emails)

You can optionally pass email addresses for disambiguation:

```
$result = NameToDomain::make($token)->resolve(
    company: 'Stripe',
    country: 'US',
    emails: ['support@stripe.com', 'sales@stripe.com']
);
```

Domain enrichment
-----------------

[](#domain-enrichment)

Domain enrichment runs asynchronously and returns richer data (favicon, trust signals, web metadata, company classification, email provider hints, etc.). There are single-company and batch flows.

### Enrich a single company

[](#enrich-a-single-company)

Create an enrichment job for one company. Poll `enrichJob(jobId)` for the result.

```
$job = NameToDomain::make($token)->enrich(
    company: 'Stripe',
    country: 'US',
    emails: ['support@stripe.com'],
    identifier: 'stripe-001'
);

// Poll for result
$result = NameToDomain::make($token)->enrichJob($job->id);
// When completed, $result->output is a JobItem with the enriched data
```

### Enrich a single company with idempotency key

[](#enrich-a-single-company-with-idempotency-key)

You can include an idempotency key to safely retry requests:

```
$job = NameToDomain::make($token)->enrich(
    company: 'Stripe',
    country: 'US',
    idempotencyKey: 'my-unique-idempotency-key'
);
```

### Enrich multiple companies (batch)

[](#enrich-multiple-companies-batch)

Create a batch enrichment job. Each item may include `company`, `country`, and optionally `emails` and `identifier`.

```
$job = NameToDomain::make($token)->enrichBatch(
    items: [
        ['company' => 'Stripe', 'country' => 'US', 'emails' => ['support@stripe.com'], 'identifier' => 'stripe-001'],
        ['company' => 'Spotify', 'country' => 'SE', 'identifier' => 'spotify-001'],
    ]
);
```

### Enrich batch with idempotency key

[](#enrich-batch-with-idempotency-key)

```
$job = NameToDomain::make($token)->enrichBatch(
    items: [['company' => 'Stripe', 'country' => 'US']],
    idempotencyKey: 'my-unique-idempotency-key'
);
```

### Get a single enrich job

[](#get-a-single-enrich-job)

Use `enrichJob` to get a single-company enrichment job. The `output` field is only present when the job is completed.

```
$result = NameToDomain::make($token)->enrichJob('01HQJXK8N3YWVF6BCMPG42X1TZ');
// $result->job and $result->output (JobItem or null)
```

### Get a batch enrich job

[](#get-a-batch-enrich-job)

Use `enrichBatchJob` to get a batch job with one page of `output` and `pagination` (when completed):

```
$result = NameToDomain::make($token)->enrichBatchJob('01HQJXK8N3YWVF6BCMPG42X1TZ', page: 1, perPage: 50);
// $result->job, $result->output (JobItem[]), $result->pagination
```

### Get batch enrich job items (paginated)

[](#get-batch-enrich-job-items-paginated)

The `enrichBatchJobItems` method returns a Saloon `Paginator` over all `JobItem` DTOs across pages.

#### Iterating over items

[](#iterating-over-items)

```
$paginator = NameToDomain::make($token)->enrichBatchJobItems(jobId: $jobId);

foreach ($paginator->items() as $item) {
    if ($item->result && $item->result['domain']) {
        echo "{$item->input['company']}: {$item->result['domain']}\n";
    }
}
```

#### Using Laravel Collections

[](#using-laravel-collections)

```
$items = NameToDomain::make($token)
    ->enrichBatchJobItems(jobId: $jobId)
    ->collect()
    ->all();
```

#### Custom pagination

[](#custom-pagination)

```
$paginator = NameToDomain::make($token)->enrichBatchJobItems(
    jobId: $jobId,
    page: 2,
    perPage: 100
);
```

#### Job item structure

[](#job-item-structure)

Each `JobItem` includes:

- `id`, `identifier` (client-supplied, if provided)
- `input` (company, country, email\_domains)
- `status`, `result`, `errorMessage`, `processedAt`

The `result` array can contain `company_normalized`, `domain`, `confidence`, and for enrichment: `favicon_url`, `trust`, `web_metadata`, `company_classification`, `email_provider_hints`.

Pagination
----------

[](#pagination)

The SDK uses [Saloon's pagination plugin](https://docs.saloon.dev/installable-plugins/pagination). The `enrichBatchJobItems()` method returns a `Paginator` that yields `JobItem` DTOs across pages. See [Saloon pagination documentation](https://docs.saloon.dev/installable-plugins/pagination) for `items()`, `collect()`, and advanced usage.

Using Saloon requests directly
------------------------------

[](#using-saloon-requests-directly)

You can use the request classes directly for full control:

```
use NameToDomain\PhpSdk\NameToDomain;
use NameToDomain\PhpSdk\Requests\Resolve\ResolveRequest;

$client = NameToDomain::make('your-api-token');
$request = new ResolveRequest('Stripe', 'US');

$response = $client->send($request)->dto();
```

Security
--------

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker.

Credits
-------

[](#credits)

- [John Trickett](https://github.com/johntrickett86/)
- [Stitch Digital](https://www.stitch-digital)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance81

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~4 days

Total

4

Last Release

103d ago

Major Versions

0.0.1 → 1.0.02026-01-16

PHP version history (2 changes)0.0.1PHP ^8.1

1.0.2PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/1afc3eb4b0906148c94893fc2c76a6832d3c5f6499f6f9ab223ec6d945ee95da?d=identicon)[johntrickett](/maintainers/johntrickett)

---

Top Contributors

[![johntrickett86](https://avatars.githubusercontent.com/u/149476912?v=4)](https://github.com/johntrickett86 "johntrickett86 (7 commits)")

---

Tags

open-sourceapisdkdomainnametodomain

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/stitch-digital-nametodomain-php-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/stitch-digital-nametodomain-php-sdk/health.svg)](https://phpackages.com/packages/stitch-digital-nametodomain-php-sdk)
```

###  Alternatives

[saloonphp/laravel-plugin

The official Laravel plugin for Saloon

765.7M125](/packages/saloonphp-laravel-plugin)[ohdearapp/ohdear-php-sdk

An SDK to easily work with the Oh Dear API

742.6M13](/packages/ohdearapp-ohdear-php-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)