PDF Manager Batch

Stability: production

A PDF Manager batch represents the asynchronous execution and eventual population of a PDF Manager template, resulting in PDF Manager zip files.

Attributes

Name Type Description Example
pdf_manager_batch:download_hrefs array When state is "available" or "success_with_errors", this is an array of hrefs that can be requested with an API key for downloading the generated PDF files. Otherwise, this is []. ["/api/v1/user_identities/1/pdf_manager_zip_files/2/download","/api/v1/user_identities/1/pdf_manager_zip_files/3/download"]
pdf_manager_batch:href string Hypertext reference to this resource.
pattern: /api/v1/user_identities/\d+/pdf_manager_batches/\d+
"/api/v1/user_identities/1/pdf_manager_batches/2"
pdf_manager_batch:id integer Unique identifier of this batch. 42
pdf_manager_batch:pdf_manager_template:href string Hypertext reference to the template.
pattern: /api/v1/user_identities/\d+/pdf_manager_templates/\d+
"/api/v1/user_identities/1/pdf_manager_templates/2"
pdf_manager_batch:pdf_manager_template:id integer Unique identifier of the template. 2
pdf_manager_batch:pdf_manager_template:name string Human-readable name of this PDF Manager template. "Accepted Offers for Review"
pdf_manager_batch:state string Current state of this batch.
one of:"initializing" or "queued" or "in_progress" or "available" or "success_with_errors" or "empty_list" or "failed"
"success_with_errors"
pdf_manager_batch:updated_at date-time Time that this batch was last updated.
pattern: \d\d\d\d-\d\d-\d\dT\d\d:\d\d:\d\dZ
"2016-01-05T16:51:00Z"

PDF Manager Batch Show

Display existing batch with download URL.

GET /api/v1/user_identities/:user_identity_id/pdf_manager_batches/:pdf_manager_batch_id

Curl Example

$ curl -n https://api.webadmit.org/api/v1/user_identities/:user_identity_id/pdf_manager_batches/:pdf_manager_batch_id \
  -H "x-api-key: 0123456789abcdef0123456789abcdef"

Response Example

HTTP/1.1 200 OK
{
  "pdf_manager_batch": {
    "href": "/api/v1/user_identities/1/pdf_manager_batches/2",
    "id": 42,
    "updated_at": "2016-01-05T16:51:00Z",
    "state": "success_with_errors",
    "download_hrefs": [
      "/api/v1/user_identities/1/pdf_manager_zip_files/2/download",
      "/api/v1/user_identities/1/pdf_manager_zip_files/3/download"
    ],
    "pdf_manager_template": {
      "href": "/api/v1/user_identities/1/pdf_manager_templates/2",
      "id": 2,
      "name": "Accepted Offers for Review"
    }
  }
}

PDF Manager Batch List

List existing batches. As there could potentially be a large number of download_hrefs, they are not displayed in this response.

GET /api/v1/user_identities/:user_identity_id/pdf_manager_batches

Curl Example

$ curl -n https://api.webadmit.org/api/v1/user_identities/:user_identity_id/pdf_manager_batches \
  -H "x-api-key: 0123456789abcdef0123456789abcdef"

Response Example

HTTP/1.1 200 OK
{
  "href": "/api/v1/user_identities/1/pdf_manager_batches",
  "pdf_manager_batches": [
    {
      "href": "/api/v1/user_identities/1/pdf_manager_batches/2",
      "id": 2,
      "updated_at": "2016-01-05T16:51:00Z",
      "state": "success_with_errors",
      "pdf_manager_template": {
        "href": "/api/v1/user_identities/1/pdf_manager_templates/2",
        "id": 2,
        "name": "Accepted Offers for Review"
      }
    }
  ]
}

PDF Manager Batch Initiate Run

Initiate the creation of a batch from a template. If you attempt to run the same batch several times in close succession, you will receive the id of the already-running instance of that batch. This is a safeguard to prevent many accidental simultaneous runs of the exact same batch: one must finish before a new one can be initiated.

POST /api/v1/user_identities/:user_identity_id/pdf_manager_batches

Required Parameters

Name Type Description Example
pdf_manager_batch:pdf_manager_template_id integer Unique identifier of the template. 2

Optional Parameters

Name Type Description Example
pdf_manager_batch:callback uri When the batch is completed, WebAdMIT will POST to this callback URL. The JSON in the callback body uses the same schema as the GET request.
pattern: ^https://
"https://example.com/my_callback"

Curl Example

$ curl -n -X POST https://api.webadmit.org/api/v1/user_identities/:user_identity_id/pdf_manager_batches \
  -d '{
  "pdf_manager_batch": {
    "pdf_manager_template_id": 2,
    "callback": "https://example.com/my_callback"
  }
}' \
  -H "Content-Type: application/json" \
  -H "x-api-key: 0123456789abcdef0123456789abcdef"

Response Example

HTTP/1.1 201 Created
{
  "pdf_manager_batch": {
    "href": "/api/v1/user_identities/1/pdf_manager_batches/2",
    "id": 42,
    "updated_at": "2016-01-05T16:51:00Z",
    "state": "success_with_errors",
    "download_hrefs": [
      "/api/v1/user_identities/1/pdf_manager_zip_files/2/download",
      "/api/v1/user_identities/1/pdf_manager_zip_files/3/download"
    ],
    "pdf_manager_template": {
      "href": "/api/v1/user_identities/1/pdf_manager_templates/2",
      "id": 2,
      "name": "Accepted Offers for Review"
    }
  }
}

Errors

Response Example

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "schema": ["The property '#/pdf_manager_batch/callback' value \"http://example.webadmit.org\" did not match the regex '^https://'"]
  }
}

Not Found

Specific error messages

When the user_identity is not found

{
  "errors": {
    "schema": [
      "User identity '999' not found."
    ]
  }
}

When the program is not found

{
  "errors": {
    "schema": [
      "Program '99999999999' not found."
    ]
  }
}

When the applicant is not found

{
  "errors": {
    "schema": [
      "Applicant '88888888888' not found."
    ]
  }
}

When the custom field is not found

{
  "errors": {
    "schema": [
      "CustomeField '42' not found."
    ]
  }
}

While these error messages are most often associated with resources that don't exist when making a GET request, please note that the same messages are also the response during POST, PUT, and PATCH requests if any resources specified by parameters cannot be found.

Generic error message (legacy error)

HTTP/1.1 404 Not Found
{
  "message": "Not Found"
}

Liaison is currently phasing out this error message in favor of more descriptive messages. If you encounter this message, please contact your Liaison representative with a detail description of the API request you made and one of our engineers will update the API.

Unauthorized

Response Example

HTTP/1.1 401 Unauthorized

(Empty response body.)