Poll for API Request Status with PHP

Share this page

Follow this PHP walkthrough to submit asynchronous document work and poll its request status with the API Polling Tool. You'll see the complete Poll for API Request Status sample first, then examine the transport code and API fields that matter when this PHP pattern moves into an application.

Why Poll for API Request Status with PHP?

Document operations can run longer than an application server, proxy, or worker should keep one HTTP response open. API Polling returns a request ID promptly and lets the caller retrieve progress through a separate status endpoint.

A PHP queue worker processing large page images can submit the conversion, release the original request path, and check status on a controlled interval. Once the job leaves pending, the worker can store the completed response or route an error for review.

The initial operation needs the response-type: requestId header. The returned identifier belongs in /request-status/{requestId}; it is not a file resource ID and should not be passed to document-processing endpoints.

PHP Code Example

require 'vendor/autoload.php'; // Require the autoload file to load Guzzle HTTP client.

use GuzzleHttp\Client; // Import the Guzzle HTTP client namespace.
use GuzzleHttp\Psr7\Request; // Import the PSR-7 Request class.
use GuzzleHttp\Psr7\Utils; // Import the PSR-7 Utils class for working with streams.

// By default, we use the US-based API service. This is the primary endpoint for global use.
$apiUrl = "https://api.pdfrest.com";

/* For GDPR compliance and enhanced performance for European users, you can switch to the EU-based service by uncommenting the URL below.
 * For more information visit https://pdfrest.com/pricing#how-do-eu-gdpr-api-calls-work
 */
//$apiUrl = "https://eu-api.pdfrest.com";

$client = new Client(); // Create a new instance of the Guzzle HTTP client

$apiKey = 'xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'; // Your API key goes here.

$headers = [
  'Api-Key' => $apiKey,
  'response-type' => 'requestId' // Use this header to obtain a request status.
];

$pngOptions = [
  'multipart' => [
    [
      'name' => 'file',
      'contents' => Utils::tryFopen('/path/to/file.pdf', 'r'),
      'filename' => 'file.pdf',
      'headers' => [
        'Content-Type' => ''
      ]
    ]
  ]
];

// Using /png as an arbitrary example, send a request with the Request-Type header.
$pngRequest = new Request('POST', $apiUrl.'/png', $headers);

$pngResponse = $client->sendAsync($pngRequest, $pngOptions)->wait();

echo $pngResponse->getBody();
echo "\r\n";

// Get the request ID from the response.
$requestId = json_decode($pngResponse->getBody())->{'requestId'};

// Get the status of the PNG request by its ID.
$request_status_endpoint_url = $apiUrl.'/request-status/'.$requestId;

$headers = [
  'Api-Key' => $apiKey
];

$request = new Request('GET', $request_status_endpoint_url, $headers);

$res = $client->sendAsync($request)->wait();

$status = json_decode($res->getBody())->{'status'};

// This example repeats the status request until the request is fulfilled.
while (strcmp($status, "pending") == 0):
  echo $res->getBody(); // Output the response body, which contains the status information.
  echo "\r\n";
  sleep(5);
  $res = $client->sendAsync($request)->wait();
  $status = json_decode($res->getBody())->{'status'};
endwhile;

echo $res->getBody();
echo "\r\n";

Source for Poll for API Request Status: View the PHP sample on GitHub.

Breaking Down the Code

Load Guzzle and its stream helpers

require 'vendor/autoload.php'; // Require the autoload file to load Guzzle HTTP client.

use GuzzleHttp\Client; // Import the Guzzle HTTP client namespace.
use GuzzleHttp\Psr7\Request; // Import the PSR-7 Request class.
use GuzzleHttp\Psr7\Utils; // Import the PSR-7 Utils class for working with streams.

Guzzle supplies the HTTP client and PSR-7 request objects used throughout the Poll for API Request Status example. For this PHP Poll for API Request Status flow, Utils::tryFopen creates readable multipart streams without loading every uploaded byte into one string.

Select the pdfRest service region

// By default, we use the US-based API service. This is the primary endpoint for global use.
$apiUrl = "https://api.pdfrest.com";

/* For GDPR compliance and enhanced performance for European users, you can switch to the EU-based service by uncommenting the URL below.
 * For more information visit https://pdfrest.com/pricing#how-do-eu-gdpr-api-calls-work
 */
//$apiUrl = "https://eu-api.pdfrest.com";

$client = new Client(); // Create a new instance of the Guzzle HTTP client

The active $apiUrl selects the US service for Poll for API Request Status; the commented assignment shows the EU alternative. Keep the PHP uploads, request IDs, and generated resources for Poll for API Request Status on that same regional host.

Submit work for asynchronous processing

$headers = [
  'Api-Key' => $apiKey,
  'response-type' => 'requestId' // Use this header to obtain a request status.
];

$pngOptions = [
  'multipart' => [
    [
      'name' => 'file',
      'contents' => Utils::tryFopen('/path/to/file.pdf', 'r'),
      'filename' => 'file.pdf',
      'headers' => [
        'Content-Type' => ''
      ]
    ]
  ]
];

// Using /png as an arbitrary example, send a request with the Request-Type header.
$pngRequest = new Request('POST', $apiUrl.'/png', $headers);

$pngResponse = $client->sendAsync($pngRequest, $pngOptions)->wait();

echo $pngResponse->getBody();
echo "\r\n";

Adding response-type: requestId changes the initial PHP processing response into an asynchronous identifier. The Poll for API Request Status operation continues normally while the PHP caller prepares its status checks.

Build the status request from the returned ID

// Get the status of the PNG request by its ID.
$request_status_endpoint_url = $apiUrl.'/request-status/'.$requestId;

$headers = [
  'Api-Key' => $apiKey
];

$request = new Request('GET', $request_status_endpoint_url, $headers);

$res = $client->sendAsync($request)->wait();

$status = json_decode($res->getBody())->{'status'};

// This example repeats the status request until the request is fulfilled.
while (strcmp($status, "pending") == 0):

The PHP code places the returned request ID into /request-status/{requestId} and authenticates the GET call. Within the PHP Poll for API Request Status flow, this tracks processing state rather than an uploaded or generated file resource.

Repeat status checks while work is pending

while (strcmp($status, "pending") == 0):
  echo $res->getBody(); // Output the response body, which contains the status information.
  echo "\r\n";
  sleep(5);
  $res = $client->sendAsync($request)->wait();
  $status = json_decode($res->getBody())->{'status'};
endwhile;

echo $res->getBody();
echo "\r\n";

The PHP status request addresses /request-status/{requestId} and repeats while the state is pending. A production PHP Poll for API Request Status implementation should impose a deadline and handle every terminal error explicitly.

Beyond the Tutorial

You can now separate pdfRest submission from completion in PHP, retain the returned request ID, and retrieve the terminal response on your own schedule.

Use a bounded polling interval, a maximum wait time, and explicit handling for terminal failure states. The sample sleeps five seconds between checks, which is a useful starting point but should fit the latency and load expectations of the calling system.

Try the Poll for API Request Status workflow with a representative file in API Lab, then adapt the request in PHP. The API Polling Tool documentation provides the complete PHP context for Poll for API Request Status values, defaults, and limitations.

How to Poll for API Request Status with PHP