Contract Upload

Uploading a contract is a three-step flow. You first ask the API for a signed upload URL, then send the file bytes straight to storage, and finally confirm the upload so the file is queued for processing. You can optionally request specific extractions to run automatically after upload.

Only PDF files are supported. Maximum file size is 50 MB.

The file bytes are uploaded directly to storage, not through the API. This removes the request-body size limit and lets you upload large contracts reliably.

Upload Flow

Mint a signed upload URL

Call POST /v1/contracts/uploads with the file metadata. This creates a staging record and returns an upload_url you can write the file to.

Upload the file to storage

Send the raw file bytes with an HTTP PUT to the returned upload_url.

Confirm the upload

Call POST /v1/contracts/uploads/complete with the stagingId. This verifies the stored file and queues it for processing.

Step 1 — Create the upload URL

Creates a new contract staging record and returns a signed URL to upload the file to.

Request

POST /v1/contracts/uploads

Query Parameters

Parameter	Type	Required	Default	Description
`projectId`	UUID	Yes	—	The project to upload the contract to

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <token>` — must be scoped to the requested project
`Content-Type`	Yes	`application/json`

Body

Field	Type	Required	Default	Description
`fileName`	string	Yes	—	The file name (e.g. `contract.pdf`)
`fileSize`	integer	Yes	—	File size in bytes (must not exceed 50 MB)
`fileType`	string	No	`application/pdf`	MIME type of the file
`fileExtension`	string	No	Inferred from `fileName`	File extension
`extractions`	array	No	—	Extraction types to run after upload

Example

curl -X POST "https://api.royaltyport.com/v1/contracts/uploads?projectId=a1b2c3d4-..." \
  -H "Authorization: Bearer rp_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "contract.pdf",
    "fileSize": 1048576,
    "extractions": ["extract-royalties", "extract-dates"]
  }'

Response

Field	Type	Description
`staging_id`	integer	Unique identifier used to confirm the upload and track processing
`upload_url`	string	Signed URL to `PUT` the file bytes to
`file_path`	string	Storage path the file will be written to

{
  "data": {
    "staging_id": 456,
    "upload_url": "https://storage.royaltyport.com/object/upload/sign/documents/...",
    "file_path": "a1b2c3d4-.../contracts_staging/..."
  }
}

Extraction Types

Pass any combination of the following extraction types to automatically process the contract after upload:

Extraction	Description
`extract-accounting-period`	Accounting period definitions
`extract-assets`	Asset references
`extract-commitments`	Commitment clauses
`extract-compensations`	Compensation terms
`extract-control-areas`	Control area definitions
`extract-costs`	Cost provisions
`extract-creative-approvals`	Creative approval clauses
`extract-dates`	Key dates (effective, termination, etc.)
`extract-royalties`	Royalty terms
`extract-signatures`	Signature information
`extract-splits`	Revenue split information
`extract-targets`	Target and threshold clauses
`extract-balances`	Balance provisions and terms

Step 2 — Upload the file

Send the raw file bytes with an HTTP PUT to the upload_url from step 1. Set Content-Type to the file’s MIME type.

curl -X PUT "<upload_url>" \
  -H "Content-Type: application/pdf" \
  --data-binary "@contract.pdf"

The fileSize and fileType you send in step 1 describe what you intend to upload. The API re-checks the actual stored file in step 3 — a file that is not a valid PDF, or that exceeds 50 MB, is rejected there.

Step 3 — Confirm the upload

Confirms the file was uploaded, verifies it, and queues it for processing.

Request

POST /v1/contracts/uploads/complete

Query Parameters

Parameter	Type	Required	Default	Description
`projectId`	UUID	Yes	—	The project the upload belongs to

Body

Field	Type	Required	Description
`stagingId`	integer	Yes	The `staging_id` returned in step 1

Example

curl -X POST "https://api.royaltyport.com/v1/contracts/uploads/complete?projectId=a1b2c3d4-..." \
  -H "Authorization: Bearer rp_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "stagingId": 456 }'

Response

Field	Type	Description
`staging_id`	integer	Identifier for tracking processing progress
`status`	string	`uploaded` once the file is confirmed and queued

{
  "data": {
    "staging_id": 456,
    "status": "uploaded"
  }
}

Track processing progress with the contract processes endpoint using the staging_id.

Errors

Status	Description
`400`	Invalid metadata, invalid extractions, file exceeds 50 MB, staging record not found, or the stored file is not a valid PDF
`403`	Token is not scoped to the requested project
`429`	Rate limit exceeded
`500`	Failed to create the upload URL, read the stored file, or a database error

Getting Started

REST API

Upload Flow

Step 1 — Create the upload URL

Request

Query Parameters

Headers

Body

Example

Response

Extraction Types

Step 2 — Upload the file

Step 3 — Confirm the upload

Request

Query Parameters

Body

Example

Response

Errors

​Upload Flow

​Step 1 — Create the upload URL

​Request

​Query Parameters

​Headers

​Body

​Example

​Response

​Extraction Types

​Step 2 — Upload the file

​Step 3 — Confirm the upload

​Request

​Query Parameters

​Body

​Example

​Response

​Errors

Upload Flow

Step 1 — Create the upload URL

Request

Query Parameters

Headers

Body

Example

Response

Extraction Types

Step 2 — Upload the file

Step 3 — Confirm the upload

Request

Query Parameters

Body

Example

Response

Errors