Download the PHP package blueink/blueink-client-php without Composer

Blueink API Client for PHP

A PHP SDK for the Blueink eSignature REST API. For full API reference see the Blueink API v2 docs.

Requirements

• PHP 8.1 or newer
• ext-json
• Guzzle 7.x (installed as a dependency)

Installation

Quickstart

Configuration

The Client constructor accepts:

Responses: NormalizedResponse

Every subclient method returns a Blueink\ClientSDK\NormalizedResponse:

The most-recent response for a given subclient is also retained:

Subclients

The Client exposes one property per resource:

Bundles

Create a Bundle from a hand-built payload:

Or use BundleHelper to assemble it. The helper exposes convenience methods for adding signers, documents, fields, and auto-placements without hand-rolling the nested payload:

When the helper has files queued via addDocumentByFile(), the SDK transparently switches the request to multipart/form-data.

Building a Bundle from a document Template

addDocumentTemplate() adds a Document backed by an existing template, with optional role assignments and initial field values. assignRole() and setValue() append to the same Document after the fact:

Other Bundle operations:

Persons

The Blueink API normalizes name by splitting on whitespace into first/last tokens, so the round-tripped name may not be byte-identical to what was sent.

Packets

Templates

Envelope Templates

Envelope templates are reusable, end-to-end Bundle workflows configured in the Blueink dashboard. The subclient is read-only:

To create a Bundle from an envelope template, configure a BundleHelper with setEnvelopeTemplate() (plus any signers and field overrides) and post it via createFromEnvelopeTemplateHelper():

For pre-built payloads, createFromEnvelopeTemplate(array $data) posts the array directly to /bundles/create_from_envelope_template/.

Webhooks

Pagination

List endpoints accept page and per_page and return a Pagination object on the response, parsed from the X-Blueink-Pagination header:

For automatic page-walking, every list-capable subclient exposes a pagedList() that returns a Paginated iterator. Each iteration yields the next page's NormalizedResponse:

Error handling

By default, 4XX/5XX responses raise a Blueink\ClientSDK\BlueinkApiError, a typed exception that parses the Blueink error body shape:

BlueinkApiError extends \RuntimeException, so a generic catch (\Throwable $e) still works. The original Guzzle BadResponseException (ClientException / ServerException) is preserved as the previous exception. Network-level failures (GuzzleHttp\Exception\ConnectException, RequestException without a response) are not wrapped and continue to bubble up unchanged.

To inspect failures without try/catch, construct the client with raise_exceptions: false. 4XX and 5XX responses then come back as NormalizedResponse objects with status and decoded data:

Testing

The SDK ships with two PHPUnit suites:

• unit (default) — fast, hermetic. Uses Guzzle's MockHandler to verify request shaping (verb, URL, headers, JSON / multipart body) without touching the network.
• integration — opt-in. Hits a real Blueink environment using the key in BLUEINK_PRIVATE_API_KEY (and optional BLUEINK_API_URL). Tests are skipped automatically when the key is absent. Use a sandbox account.

License

MIT.