Back to Blog
PHPAPIeSignature

PHP eSignature API: Complete Integration Guide with PDFSignify

PDFSignify TeamFebruary 18, 202612 min read

Integrating digital signatures into a PHP application does not require complex libraries or multi-step async workflows. The PDFSignify API provides three focused endpoints that handle certificate-based PDF signing, metadata management, and certificate validation. Every call is synchronous — you send the request and get the result back immediately.

API Overview

The PDFSignify API has three endpoints, all using multipart/form-data requests:

  • POST /api/v1/sign-pdf — Sign a PDF with a digital certificate. Returns the signed PDF as binary data.
  • POST /api/v1/set-pdf-metadata — Update metadata fields on a PDF (author, title, keywords, etc.). Returns the updated PDF.
  • POST /api/v1/check-certificate-password — Validate that a certificate file and password are correct. Returns a JSON response.

Authentication

Every request requires two headers: AccessKey and SecretKey. There are no Bearer tokens, no OAuth flows, and no session management. You get your credentials from the PDFSignify dashboard and include them on every request.

php
<?php
$headers = [
    'AccessKey: YOUR_ACCESS_KEY',
    'SecretKey: YOUR_SECRET_KEY',
];

Endpoint 1: Sign a PDF with a Digital Certificate

This is the primary endpoint. You send a PDF file, a .pfx or .p12 certificate, and the certificate password. The API applies a cryptographic digital signature and returns the signed PDF as binary data.

Required Fields

  • pdf — the PDF file to sign
  • certificate — the .pfx or .p12 digital certificate file
  • certificatePassword — the password for the certificate

Optional Fields

  • signatureBackgroundImage — custom image for the signature appearance
  • signaturePageAppearance — page number to display the signature (-1 for all pages)
  • signatureMessage, signatureDateLabel, signatureDateFormat — customize the signature text
  • signatureHeight, signatureWidth, signatureXPosition, signatureYPosition — control signature placement
  • timezone — timezone for the signing timestamp
  • pdfMetadataAuthor, pdfMetadataTitle, pdfMetadataSubject, pdfMetadataKeywords, and other metadata fields

Simple Example Using CURLFile

php
<?php
$ch = curl_init('https://api.pdfsignify.com/api/v1/sign-pdf');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'AccessKey: YOUR_ACCESS_KEY',
        'SecretKey: YOUR_SECRET_KEY',
    ],
    CURLOPT_POSTFIELDS => [
        'certificate' => new CURLFile('certificate.pfx', 'application/x-pkcs12'),
        'certificatePassword' => 'your_certificate_password',
        'pdf' => new CURLFile('document.pdf', 'application/pdf'),
    ],
]);

$response = curl_exec($ch);

if ($response === false) {
    die('cURL Error: ' . curl_error($ch));
}

$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE);
curl_close($ch);

if (strpos($contentType, 'application/pdf') !== false) {
    file_put_contents('signed_document.pdf', $response);
    echo 'PDF signed successfully.';
} else {
    echo 'Signing failed: ' . $response;
}

Full Example with Signature Customization

For complete control over the signature appearance, position, and PDF metadata, you need to build the multipart body manually:

php
<?php
$cert = file_get_contents('certificate.pfx');
$pdf = file_get_contents('document.pdf');
$logo = file_get_contents('company_logo.png');

$boundary = uniqid();
$delimiter = '--------------------' . $boundary;
$data = [];

$data[] = '--' . $delimiter;
$data[] = 'Content-Disposition: form-data; name="certificate"; filename="certificate.pfx"';
$data[] = 'Content-Type: application/x-pkcs12';
$data[] = '';
$data[] = $cert;

$data[] = '--' . $delimiter;
$data[] = 'Content-Disposition: form-data; name="certificatePassword"';
$data[] = '';
$data[] = 'your_certificate_password';

$data[] = '--' . $delimiter;
$data[] = 'Content-Disposition: form-data; name="pdf"; filename="document.pdf"';
$data[] = 'Content-Type: application/pdf';
$data[] = '';
$data[] = $pdf;

$data[] = '--' . $delimiter;
$data[] = 'Content-Disposition: form-data; name="signatureBackgroundImage"; filename="company_logo.png"';
$data[] = 'Content-Type: image/png';
$data[] = '';
$data[] = $logo;

$fields = [
    'pdfMetadataAuthor' => 'Acme Corp',
    'pdfMetadataTitle' => 'Service Agreement',
    'pdfMetadataSubject' => 'Contract',
    'pdfMetadataKeywords' => 'contract,agreement,signed',
    'pdfMetadataCreator' => 'Acme CRM',
    'pdfMetadataProducer' => 'PDFSignify',
    'pdfMetadataCreationDate' => date('Y-m-d H:i:s'),
    'pdfMetadataModificationDate' => date('Y-m-d H:i:s'),
    'signaturePageAppearance' => '-1',
    'timezone' => 'Europe/London',
    'signatureMessage' => 'Digitally signed by Acme Corp',
    'signatureDateLabel' => '',
    'signatureDateFormat' => 'Y-m-d H:i:s',
    'signatureHeight' => '100',
    'signatureWidth' => '150',
    'signatureYPosition' => '100',
    'signatureXPosition' => '180',
];

foreach ($fields as $key => $value) {
    $data[] = '--' . $delimiter;
    $data[] = 'Content-Disposition: form-data; name="' . $key . '"';
    $data[] = '';
    $data[] = $value;
}

$data[] = '--' . $delimiter . '--';
$data[] = '';
$postData = implode("\r\n", $data);

$ch = curl_init('https://api.pdfsignify.com/api/v1/sign-pdf');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: multipart/form-data; boundary=' . $delimiter,
    'AccessKey: YOUR_ACCESS_KEY',
    'SecretKey: YOUR_SECRET_KEY',
]);

$response = curl_exec($ch);

if ($response === false) {
    echo 'cURL Error: ' . curl_error($ch);
} else {
    $contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE);
    if (strpos($contentType, 'application/pdf') !== false) {
        file_put_contents('signed_document.pdf', $response);
        echo 'Signed PDF saved successfully.';
    } else {
        echo 'Error: ' . $response;
    }
}

curl_close($ch);

Endpoint 2: Set PDF Metadata

This endpoint updates the metadata fields of a PDF without signing it. It is useful when you need to set author information, titles, or keywords on documents before distribution or archival. The API returns the updated PDF as binary data.

php
<?php
$ch = curl_init('https://api.pdfsignify.com/api/v1/set-pdf-metadata');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'AccessKey: YOUR_ACCESS_KEY',
        'SecretKey: YOUR_SECRET_KEY',
    ],
    CURLOPT_POSTFIELDS => [
        'pdf' => new CURLFile('document.pdf', 'application/pdf'),
        'pdfMetadataAuthor' => 'Acme Corp',
        'pdfMetadataTitle' => 'Q1 Report',
        'pdfMetadataSubject' => 'Quarterly Financial Report',
        'pdfMetadataKeywords' => 'finance,quarterly,report',
        'pdfMetadataCreator' => 'Acme Reporting Tool',
        'pdfMetadataProducer' => 'PDFSignify',
    ],
]);

$response = curl_exec($ch);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE);
curl_close($ch);

if (strpos($contentType, 'application/pdf') !== false) {
    file_put_contents('document_with_metadata.pdf', $response);
    echo 'Metadata updated successfully.';
} else {
    echo 'Error: ' . $response;
}

Endpoint 3: Check Certificate Password

Before signing, you may want to validate that a certificate and its password are correct. This is especially useful when end users upload their own certificates. The endpoint returns a JSON response indicating whether the credentials are valid.

php
<?php
$ch = curl_init('https://api.pdfsignify.com/api/v1/check-certificate-password');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'AccessKey: YOUR_ACCESS_KEY',
        'SecretKey: YOUR_SECRET_KEY',
    ],
    CURLOPT_POSTFIELDS => [
        'certificate' => new CURLFile('certificate.pfx', 'application/x-pkcs12'),
        'certificatePassword' => 'your_certificate_password',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);

if ($result['success'] ?? false) {
    echo 'Certificate is valid. Proceeding with signing...';
} else {
    echo 'Certificate validation failed. Check the file and password.';
}

Building a Complete Signing Workflow

In a real application, you would combine these endpoints. A typical workflow looks like this:

  • User uploads a PDF and a .pfx certificate through your application
  • Your PHP backend calls check-certificate-password to validate the certificate
  • If valid, call sign-pdf with the PDF, certificate, and desired options
  • Save the signed PDF or stream it back to the user for download
  • Optionally use set-pdf-metadata to standardize metadata across documents

Error Handling Best Practices

  • Always check curl_error() for network failures before inspecting the response
  • Check the Content-Type header — sign-pdf and set-pdf-metadata return application/pdf on success, not JSON
  • Check the HTTP status code with curl_getinfo($ch, CURLINFO_HTTP_CODE) to detect 4xx/5xx errors
  • Store your AccessKey and SecretKey in environment variables, never hardcode them
  • Log errors with enough context to debug but never log the SecretKey

Why This Approach Works

The PDFSignify API is designed for developers who need to sign PDFs without managing signing infrastructure. There are no document queues, no webhook handlers to maintain, no signer email flows, and no stored state. Your PHP application stays in full control of the workflow. The API does exactly one thing per call and does it well.

Three endpoints, no state, immediate results. That is the entire API — and it is all you need.