1. Make a simple receipt layout

Open Templates and create a PDF template named Customer receipt. In Design, add a text element for the heading and a second text element for the customer’s name.

Keep the design simple for now. Our goal is to see one value travel from the data we send into the finished receipt.

2. Leave a place for the customer’s name

Open Data and add a Text variable named customer_name. Back in Design, select the customer-name text element and enter the text below.

The double braces mean “put this variable’s value here.” So Receipt for {{customer_name}} becomes Receipt for Ada when we supply Ada. The name inside the braces must match the variable in Data.

Receipt for {{customer_name}}

3. See the substitution happen

Open Preview, set customer_name to Ada, and generate the preview. Look for Receipt for Ada in the document.

Now try Sam and generate it again. The layout should stay the same while the name changes. If the name is missing, compare customer_name in Data with the text inside your braces before continuing.

{
  "customer_name": "Ada"
}

4. Generate it from your app

Publish changes and open API. Copy the template_id and template_revision_id from the generated example and use them in place of the placeholders below.

The template ID identifies your design; the revision ID selects a particular version of it. Under data, we’re sending the same customer_name value you tried in Preview. Run the request with your API key, then keep the returned run id for the next step.

curl --request POST "https://api.uselongrun.app/v1/pdf/render-template" \
  --header "Authorization: Bearer ${API_KEY}" \
  --header "Content-Type: application/json" \
  --data "$(jq -n --arg TEMPLATE_ID "${TEMPLATE_ID}" --arg TEMPLATE_REVISION_ID "${TEMPLATE_REVISION_ID}" '{
  "inputs": {
    "template_id": $TEMPLATE_ID,
    "template_revision_id": $TEMPLATE_REVISION_ID,
    "data": {
      "customer_name": "Ada"
    }
  }
}')"

{
  "id": "run_example",
  "status": "queued",
  "outputs": null,
  "error": null
}

5. Wait for the result

Now let’s ask about the work we just submitted. Replace RUN_ID below with the real run id you copied, then run the command.

Look at status in the response. queued means it is waiting; running means it is being processed. Wait 2 seconds before checking again. When you see completed, you can move to the download. If you see failed or cancelled, stop and inspect the error instead.

For this exercise, stop checking after 2 minutes. That does not cancel the work—you can return to Runs to check it later.

curl --request GET "https://api.uselongrun.app/v1/runs/${RUN_ID}" \
  --header "Authorization: Bearer ${API_KEY}"

6. Download and check the file

Once status is completed, look inside outputs.file for the file id. We used the run id to check the work; now we need the file id to retrieve what it produced.

Replace FILE_ID with that id and run the download command. It saves the LongRun file as result.pdf in your current folder. Open it and check the content. You’ve now followed a request all the way from input to a usable file. The response example below shows only the fields we need for this step.

{
  "id": "run_example",
  "status": "completed",
  "outputs": {
    "file": {
      "id": "file_result",
      "name": "result.pdf",
      "mime_type": "application/pdf"
    }
  },
  "error": null
}

curl --fail-with-body "https://api.uselongrun.app/v1/files/${FILE_ID}/content" \
  --header "Authorization: Bearer ${API_KEY}" \
  --output result.pdf

If something goes wrong

If the request returns 401, check the API key. If the run fails, read error.message and open its details in Runs. Correct the input before submitting another run. A 202 response means accepted, not finished.