Quickstart

Learn how to generate your first PDF document.

To get started you’ll need an Amazon Web Services account so that PDFs can be uploaded to S3, Amazon’s cloud storage service. If you don’t already have an account, sign up here. New accounts get 5GB of storage free for a year.

Paperplane stores all your generated PDFs on your own S3 cloud storage bucket. If you don’t know how to create an S3 bucket, follow the instructions under “Setting up an S3 bucket” before coming back here.

Now that you have an S3 bucket created, Paperplane needs to be able to upload files to it. To do this you'll create an AWS user and generate credentials which are used to upload to S3.

Creating an AWS user

First, navigate to the "IAM" service in the AWS console.

Next, navigate to "Users". You'll see a screen looking something like this:

Next, click "Add user" and choose a suitable user name. Make sure that "Programmatic access" is enabled:

Click through to "Permissions" and select the option to attach the "AmazonS3FullAccess" policy directly to the user:

Click through the following steps, and finally create the user.

Using the "AllowS3FullAccess" policy is the easiest way to get started, but gives Paperplane broad access to your S3 buckets. You may want to take a look at the guide on restricting AWS permissions which explains how to restrict access using a minimal set of permissions.

In the S3 section of the AWS console, click on your bucket name, then go to the “Permissions” tab. Click “Bucket Policy” then paste in the bucket policy from the “Setting up an S3 bucket” article.

After creating the user, you'll be able to download the "Access key ID" and "Secret access key". Make sure to save these as you won't be able to access the secret key again (although you can easily generate a new set of credentials).

Viewing the access key and secret key for the new user

Generating your first PDF

To confirm the user is properly set up, let’s go to Paperplane and create a new "Destination".

Go to dash.paperplane.app and sign in to your account.

Under “Destination”, click “New Destination”. Enter the AWS credentials, bucket name and bucket region:

Finally, click "Create API Key" to add an API key to the destination:

Choose an appropriate name to identify the API key:

Your API key is now ready to use!

Now you’re ready to create a PDF. Here’s an example of creating a new PDF job using the curl command line utility:

Replace myapikey with the API key you just generated.

$ curl -u myapikey: https://api.paperplane.app/jobs -d url="https://en.wikipedia.org/wiki/Airplane"

{
  "id": "fe748521-5d8f-43d8-9093-7970d2d032d7",
  "url": "https://en.wikipedia.org/wiki/Airplane",
  "status": "queued",
  "done": false,
  "object": "job"
}

The URL you supply must be publicly accessible so that Paperplane can load it. However, you can use an unguessable key such as a UUID in the URL to ensure data remains private. For more details, check out the guide on “Securing access to HTML documents”.

When you create a new job, the API returns the job’s ID and current status, which will initially be queued. Soon afterwards (normally within 30 seconds) Paperplane will start processing the job by visiting the URL, saving a PDF and uploading it to your S3 bucket. You can check the status of the job by using its ID. Here’s an example using curl:

$ curl -u myapikey: https://api.paperplane.app/jobs/fe748521-5d8f-43d8-9093-7970d2d032d7

{
  "id": "fe748521-5d8f-43d8-9093-7970d2d032d7",
  "url": "https://en.wikipedia.org/wiki/Airplane",
  "status": "delivered",
  "done": true,
  "object": "job"
}

When the PDF has been delivered to S3, the job status will update to delivered. If the job fails for any reason, that status will update to either creation_failed or delivery_failed. More details on the job statuses can be found in the API reference.

That’s it - you’ve created your first PDF! For details on all the configuration options available, check out “Customizing the PDF”.