Skip to main content
This guide walks you through the complete end-to-end flow for processing a construction document with the Plangrep API: create a project, create a job, upload a file, complete the upload, poll for job status, and fetch your normalized JSON results.

​
Prerequisites

  • A Plangrep account
  • An API key — see Authentication to create one
  • A PDF file to process

​
Steps

1

Create a project

Send a POST request to create a new project. Projects act as containers for all the jobs and documents you process together.
curl -X POST https://plangrep.com/api/open/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "My First Project" }'
Request body
{ "name": "My First Project" }
Response (202)
{
  "project": {
    "id": "proj_abc123",
    "status": "provisioning"
  },
  "billing": { }
}
Project creation is asynchronous and takes 1–2 minutes to provision. Poll GET /api/open/v1/projects/{projectId} every 10 seconds until project.status equals "ready". Stop polling and surface an error if the project has not reached "ready" within 5 minutes.
curl https://plangrep.com/api/open/v1/projects/proj_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
2

Create a job

Once your project is "ready", create a job inside it. A job represents a single processing run over one or more uploaded files.
curl -X POST https://plangrep.com/api/open/v1/projects/proj_abc123/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Request body
{}
All fields are optional. You can pass a webhookUrl here to receive a callback when the job finishes instead of polling — see Step 5 for details.Response (202)
{
  "job": {
    "id": "job_xyz789",
    "status": "awaiting_uploads"
  }
}
3

Upload a file

Upload one or more files to the job using a multipart/form-data request. Include a metadata part (a JSON string) that describes each file part, followed by the file parts themselves named file0, file1, and so on.
curl -X POST https://plangrep.com/api/open/v1/jobs/job_xyz789/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F 'metadata={"files":[{"partName":"file0","fileName":"drawings.pdf","contentType":"application/pdf"}]}' \
  -F '[email protected]'
ResponseThe response includes an uploads array with a documentId for each file received. Save these IDs if you need to reference individual documents later.
4

Complete uploads and start processing

Signal to Plangrep that all files have been uploaded and processing should begin.
curl -X POST https://plangrep.com/api/open/v1/jobs/job_xyz789/uploads/complete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Request body
{}
An empty JSON body completes all server-stored files for this job.Response (202)
{
  "job": {
    "status": "preflighting"
  }
}
Plangrep now validates your uploads and begins processing.
5

Poll for completion

Poll GET /api/open/v1/jobs/{jobId} until the job reaches a terminal status.
curl https://plangrep.com/api/open/v1/jobs/job_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"
Job status values
StatusDescription
provisioningJob is being set up
awaiting_uploadsReady to receive file uploads
uploadingFile upload in progress
preflightingValidating uploads before processing
blocked_insufficient_creditsJob is paused — top up credits to continue
processingActively extracting and normalizing data
completedAll documents processed successfully
completed_with_errorsProcessing finished with one or more document errors
failedJob failed and cannot be retried
cancelledJob was cancelled before completion
expiredJob expired before processing completed
Continue polling until job.status is one of: completed, completed_with_errors, failed, cancelled, or expired.
For webhook-driven workflows, pass a webhookUrl in the job creation request body instead of polling. Plangrep will POST the final job status to your endpoint as soon as processing finishes.
6

Fetch results

Once the job status is completed or completed_with_errors, fetch the normalized JSON output.
curl https://plangrep.com/api/open/v1/jobs/job_xyz789/result \
  -H "Authorization: Bearer YOUR_API_KEY"
The response is a Result object with the following top-level fields:
FieldDescription
jobSummary of the job and its final status
usageCredit usage breakdown for this job
documentsProcessed documents, each containing sheets, specifications, and docs arrays
evidenceCitable source records — individual sheets, regions, and spec sections that back the extracted data
warningsNon-fatal issues encountered during processing
errorsErrors for documents that could not be fully processed

​
Next steps

For a deeper look at upload options — including how to reference previously uploaded files and how to structure multi-file jobs — see the Submit a Job guide.