Background Job Check#

Checks the status of a background job that was previously created with PDF.co API. Use this API to check the status of your asynchronous API calls.

Available Methods#

/job/check#

  • Method: POST

  • Endpoint: /v1/job/check

Attributes#

Note

Attributes are case-sensitive and should be inside JSON for POST request, for example:

{
    "jobId": "6YSZD3U872ZYYFEDMQCQSGEEO8YSF5WA--151-300"
}

Attribute

Description

Required

jobId

ID of background that was started asynchronously. To start a new async background job, you should set async to true for API methods.

yes

force

Set to true to forcibly check the status of the background job. Intended to be used with really long and heavy background jobs only.

no

Returns JSON with the status of the background job.

Available status values#

  • working background job is currently in work or does not exist.

  • success background job was successfully finished.

  • failed background job failed for some reason (see message for more details).

  • aborted background job was aborted.

  • unknown unknown background job id. Available only when force is set to true for input request.

Query parameters#

No query parameters accepted.

Payload#

{
  "jobid": "6YSZD3U872ZYYFEDMQCQSGEEO8YSF5WA--151-300"
}

Response 2#

{
  "status": "working",
  "remainingCredits": 60227
}

{
   "status": "success",
   "message": "Success",
   "url": "https://pdf-temp-files.s3.us-west-2.amazonaws.com/6YSZD3U872ZYYFEDMQCQSGEEO8YSF5WA--151-300/L8QYIZQ6KZOITCT0PXUNPM6HKYSP5OIO.json?X-Amz-Expires=3600&X-Amz-Security-Token=FwoGZXIvYXdzECcaDAbrXwAd1IYG3nZR5yKCAdcavWT%2BuwTotGsad9asqRzowPa1M4BoIWU0M9FqXNJP8xBIQX1Cn7XTq4ZfpklsxcpGE4WcapfHdooi2uR1QWw4kuUlMGGU92uy7pS0RhaGCEL00ES%2BIb%2F5039yyAFklqfAgDlHvi47I7Pp01y6Ua25RzrZGh6ACOd7le%2BXArnbQs4o4ezNqgYyKD%2FCX1I5ZOS0tu0ND0I%2FUWTHp6OR8He9a0dgVXfiMU7pNkwQqwVVFcM%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA4NRRSZPHAZTLLKK5/20231114/us-west-2/s3/aws4_request&X-Amz-Date=20231114T134932Z&X-Amz-SignedHeaders=host&X-Amz-Signature=e5553e080a23fb158c0514f99c9f70be0cb74f764933d712ba628110d4079b4c",
   "jobId": "6YSZD3U872ZYYFEDMQCQSGEEO8YSF5WA--151-300",
   "credits": 2,
   "remainingCredits": 1480582,
   "duration": 33
}

CURL#

curl --location --request POST 'https://api.pdf.co/v1/job/check' \
--header 'x-api-key: ' \
--data-raw '{
    "jobid": "6YSZD3U872ZYYFEDMQCQSGEEO8YSF5WA--151-300"
}'

Code samples#

var https = require("https");
var path = require("path");
var fs = require("fs");

// The authentication key (API Key).
// Get your own by registering at https://app.pdf.co
const API_KEY = "***********************************";
const jobId = "{your_job_id}";

let queryPath = `/v1/job/check`;

// JSON payload for api request
let jsonPayload = JSON.stringify({
    jobid: jobId
});

let reqOptions = {
    host: "api.pdf.co",
    path: queryPath,
    method: "POST",
    headers: {
        "x-api-key": API_KEY,
        "Content-Type": "application/json",
        "Content-Length": Buffer.byteLength(jsonPayload, 'utf8')
    }
};

// Send request
var postRequest = https.request(reqOptions, (response) => {
    response.on("data", (d) => {
        response.setEncoding("utf8");

        // Parse JSON response
        let data = JSON.parse(d);
        console.log(`Checking Job #${jobId}, Status: ${data.status}, Time: ${new Date().toLocaleString()}`);

        if (data.status == "success") {
            console.log(`Job success!`);
        }
        else {
            console.log(`Operation ended with status: "${data.status}".`);
        }
    })
});

import os
import requests # pip install requests

# The authentication key (API Key).
# Get your own by registering at https://app.pdf.co
API_KEY = "******************************************"
jobId = "******************************************"

# Base URL for PDF.co Web API requests
BASE_URL = "https://api.pdf.co/v1"

url = f"{BASE_URL}/job/check?jobid={jobId}"

response = requests.get(url, headers={ "x-api-key": API_KEY })
if (response.status_code == 200):
    json = response.json()
    return json["status"]
else:
    print(f"Request error: {response.status_code} {response.reason}")

package com.company;

import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import com.google.gson.JsonPrimitive;
import okhttp3.*;

public class Main
{
    // The authentication key (API Key).
    // Get your own by registering at https://app.pdf.co
    final static String API_KEY = "***********************************";

    public static void main(String[] args) throws IOException
    {
      // Prepare POST request body in JSON format
      JsonObject jsonBody = new JsonObject();
      jsonBody.add("jobid", new JsonPrimitive(jobId));

      RequestBody body = RequestBody.create(MediaType.parse("application/json"), jsonBody.toString());

      // Prepare request to `Job Check` API
      Request request = new Request.Builder()
              .url("https://api.pdf.co/v1/job/check")
              .addHeader("x-api-key", API_KEY) // (!) Set API Key
              .addHeader("Content-Type", "application/json")
              .post(body)
              .build();

      // Execute request
      Response response = webClient.newCall(request).execute();
    }
}

<?

  function CheckJobStatus($jobId, $apiKey)
  {
      $status = null;

      // Create URL
      $url = "https://api.pdf.co/v1/job/check";

      // Prepare requests params
      $parameters = array();
      $parameters["jobid"] = $jobId;

      // Create Json payload
      $data = json_encode($parameters);

      // Create request
      $curl = curl_init();
      curl_setopt($curl, CURLOPT_HTTPHEADER, array("x-api-key: " . $apiKey, "Content-type: application/json"));
      curl_setopt($curl, CURLOPT_URL, $url);
      curl_setopt($curl, CURLOPT_POST, true);
      curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
      curl_setopt($curl, CURLOPT_POSTFIELDS, $data);

      // Execute request
      $result = curl_exec($curl);

      if (curl_errno($curl) == 0)
      {
          $status_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);

          if ($status_code == 200)
          {
              $json = json_decode($result, true);

              if (!isset($json["error"]) || $json["error"] == false)
              {
                  $status = $json["status"];
              }
              else
              {
                  // Display service reported error
                  echo "<p>Error: " . $json["message"] . "</p>";
              }
          }
          else
          {
              // Display request error
              echo "<p>Status code: " . $status_code . "</p>";
              echo "<p>" . $result . "</p>";
          }
      }
      else
      {
          // Display CURL error
          echo "Error: " . curl_error($curl);
      }

      // Cleanup
      curl_close($curl);

      return $status;
  }

?>

Footnotes

1

Supports links from Google Drive, Dropbox, and PDF.co Built-In Files Storage. To upload files via the API check out the File Upload section. Note: If you experience intermittent Access Denied or Too Many Requests errors, please try to add cache: to enable built-in URL caching. (e.g cache:https://example.com/file1.pdf) For data security, you have the option to encrypt output files and decrypt input files. Learn more about user-controlled data encryption.

2

Main response codes as follows:

Code

Description

200

Success

400

Bad request. Typically happens because of bad input parameters, or because the input URLs can’t be reached, possibly due to access restrictions like needing a login or password.

401

Unauthorized

402

Not enough credits

445

Timeout error. To process large documents or files please use asynchronous mode (set the async parameter to true) and then check status using the /job/check endpoint. If a file contains many pages then specify a page range using the pages parameter. The number of pages of the document can be obtained using the /pdf/info endpoint.

Note

For more see the complete list of available response codes.