SIGN PDF API · PHP
Sign a PDF in PHP.
This sign PDF API in PHP example sends a template to one person, who signs on any device. Make a test key and a template, then run it. A test key sends nothing real and bills nothing.
SIGNED
Signed
PHP
<?php
require __DIR__ . '/vendor/autoload.php';
$config = Docustay\Configuration::getDefaultConfiguration()->setAccessToken(getenv('DOCUSTAY_API_KEY'));
if ($url = getenv('DOCUSTAY_URL')) {
$config->setHost($url);
}
$api = new Docustay\Api\DocumentsApi(new GuzzleHttp\Client(), $config);
$request = new Docustay\Model\SendRequest([
'template_id' => getenv('DOCUSTAY_TEMPLATE_ID'),Send, listen, download
Three steps, one program.
1 · Install
Add the client.
composer require docustay/docustay-php
The package needs PHP 7.4 or newer with the curl and json extensions, and uses Guzzle. The first argument of each call that creates something is an idempotency key: build one per attempt and reuse it when you retry. Pass the host only when you point at a self-hosted install.
2 · Send
send.php
<?php
require __DIR__ . '/vendor/autoload.php';
$config = Docustay\Configuration::getDefaultConfiguration()->setAccessToken(getenv('DOCUSTAY_API_KEY'));
if ($url = getenv('DOCUSTAY_URL')) {
$config->setHost($url);
}
$api = new Docustay\Api\DocumentsApi(new GuzzleHttp\Client(), $config);
$request = new Docustay\Model\SendRequest([
'template_id' => getenv('DOCUSTAY_TEMPLATE_ID'),
'parties' => [new Docustay\Model\SendRequestPartiesInner([
'seat' => 'signer_1', 'name' => 'Rosa Alvarez', 'email' => 'rosa@example.com',
])],
]);
$doc = $api->sendDocument(bin2hex(random_bytes(16)), $request);
echo $doc->getId(), ' ', $doc->getState(), PHP_EOL;This sends the template to one person. It reads the key and the template id from the environment.
3 · Then
Read the answer.
The PHP program's answer holds the document's id and its state. Ask for it later with the same key, or get a signed webhook when it is signed. The quickstart shows the rest.
What happens next
One composer require, and a plain script or a framework app sends it.
The signer needs no account and nothing installed; you read the result from the document.
The request, by hand
What the PHP program sends.
| Part | Value |
|---|---|
| Method and path | POST /api/v1/documents/send |
| Authorization | Bearer, then your API key |
| Content-Type | application/json |
| Idempotency-Key | A fresh UUID for each document; keep it if you retry |
| Body | templateId and parties: a seat, a name and an email for each person |
The same request works from any language that can make an HTTPS call.
Line by line
What the PHP program does.
Read it once and you can change it with confidence.
Only curl
The example uses the curl functions that most PHP builds ship with, so there is nothing to install.
Build the JSON body
json_encode makes the body from an array: the templateId and one party for seat signer_1. A template with two signers needs two parties.
Set the three headers
Authorization carries the bearer key, Content-Type says JSON, and Idempotency-Key is made with random_bytes. Keep that value if you retry.
Check the status
A status of 300 or more writes the body to standard error and exits 1; otherwise the program prints the answer, which holds the document's id and its state.
When it goes wrong
Errors and retries in PHP.
Every error from the API has the same shape: kind, a plain message, a requestId and a retryable flag.
Read the error object yourself
A failure comes back as a JSON object with a kind, a message, a requestId and a retryable flag. Decode it with json_decode and log the requestId.
Retries are yours to write
Retry a 429 after the seconds in Retry-After and a 5xx after a pause, with the same Idempotency-Key each time. A generated PHP client is available if you would rather not write that loop.
What is safe to retry
In PHP, as anywhere, a 429 and a 5xx are safe to retry with the same Idempotency-Key: sending the same request again never sends a second document. A 400, 401, 403, 404 or 409 will give the same answer every time, so fix the cause before you try again.
Before you run it
What you need on hand.
Three things, none of them hard to get.
PHP with the curl extension
Nothing to install. Check that curl is enabled in your PHP build.
A test key
Make a key in the app under Developers, then API keys, and tick documents:read and documents:write. Give it to the PHP program through DOCUSTAY_API_KEY. A key that starts dsk_test_ only does practice runs: the email goes to you and nothing counts.
A template id
Use your own copy of a built-in template, or one you made from HTML or a tagged PDF, and put its id in DOCUSTAY_TEMPLATE_ID before you run the PHP file. Its seat names, such as signer_1, are what the parties in the request refer to.
Run it
Save the program as send.php. It prints the document's id and its state, and the test email arrives in your own inbox within a minute or so.
Questions
Quick answers.
Does a test key send anything real?
No. A document sent with a dsk_test_ key is emailed only to you, carries a TEST watermark and is never counted.
Where do the key and template id come from?
From the environment: DOCUSTAY_API_KEY and DOCUSTAY_TEMPLATE_ID. The key never sits in the file.
How do I know it was signed?
Subscribe to documents.document.executed, or fetch the document by id.