Error
A valid request URL is required to generate request examples{
"statusCode": 401,
"message": "Unauthorized"
}
Files API
Generate Upload URL
Generate a presigned URL for direct upload of signed release forms to cloud storage
GET
/
files
/
release-form
/
generate-upload-url
Error
A valid request URL is required to generate request examples{
"statusCode": 401,
"message": "Unauthorized"
}
Generate Release Form Upload URL
Generates a presigned URL that allows direct upload of signed release forms to cloud storage. This enables clients to upload release form PDFs directly without proxying through the API server.Authentication
Required - Bearer token authentication. The tenant context is extracted from the JWT token.Response
string
A presigned URL valid for 15 minutes that allows direct PUT upload to cloud storage
string
The GCS URI (
gs://bucket/path) where the file will be stored. Use this value as signedReleaseFileUrl when creating verification orders. Alternatively, you can pass an HTTPS URL or inline base64 PDF directly in signedReleaseFileUrl — see Signed release file.Example Request
curl -sS -X GET "https://sandbox.theary.ai/files/release-form/generate-upload-url" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Accept: application/json"
const response = await fetch('https://sandbox.theary.ai/files/release-form/generate-upload-url', {
headers: {
'Authorization': 'Bearer YOUR_JWT_TOKEN'
}
})
const { signedUrl, fileUri } = await response.json()
import requests
response = requests.get(
'https://sandbox.theary.ai/files/release-form/generate-upload-url',
headers={'Authorization': 'Bearer YOUR_JWT_TOKEN'}
)
data = response.json()
signed_url = data['signedUrl']
file_uri = data['fileUri']
Example Response
{
"signedUrl": "https://storage.googleapis.com/verification-api-storage/tenants/acme-corp/releaseForms/550e8400-e29b-41d4-a716-446655440000.pdf?X-Goog-Algorithm=...",
"fileUri": "gs://verification-api-storage/tenants/acme-corp/releaseForms/550e8400-e29b-41d4-a716-446655440000.pdf"
}
Uploading the File
After obtaining the signed URL, upload your PDF file directly to cloud storage:# Upload the release form PDF
curl -sS -X PUT "${SIGNED_URL}" \
-H "Content-Type: application/pdf" \
--data-binary @signed-release-form.pdf
// Upload the release form PDF
const fileBuffer = await fs.promises.readFile('signed-release-form.pdf')
await fetch(signedUrl, {
method: 'PUT',
headers: {
'Content-Type': 'application/pdf'
},
body: fileBuffer
})
# Upload the release form PDF
with open('signed-release-form.pdf', 'rb') as f:
requests.put(
signed_url,
headers={'Content-Type': 'application/pdf'},
data=f.read()
)
Using the File URI
After uploading, use thefileUri as the signedReleaseFileUrl when creating a verification order:
{
"applicant": {
"firstName": "John",
"lastName": "Smith",
"ssn": "123-45-6789",
"signedReleaseFileUrl": "gs://verification-api-storage/tenants/acme-corp/releaseForms/550e8400-e29b-41d4-a716-446655440000.pdf"
},
// ... rest of order
}
File Storage
Files are organized by tenant for security and isolation:gs://verification-api-storage/
└── tenants/
└── {tenant-name}/
└── releaseForms/
└── {uuid}.pdf
Important Notes
- URL Expiration: The signed URL expires after 15 minutes
- File Type: Only PDF files are supported (
application/pdf) - File Size: There is currently no server-side size limit enforced on files uploaded through this signed-URL flow. As a best practice, keep uploads reasonably sized (a signed release form is typically well under 1MB). The 10MB cap documented for
signedReleaseFileUrlapplies only to the separate inline base64 upload path used by Create order — it does not apply here. - Tenant Isolation: Files are stored in tenant-specific directories
- Security: Files can only be accessed by the owning tenant
Response Codes
| Status Code | Description |
|---|---|
200 | Upload URL generated successfully |
401 | Unauthorized - invalid or missing JWT token |
500 | Internal server error |
Error Responses
{
"statusCode": 401,
"message": "Unauthorized"
}
{
"statusCode": 500,
"message": "Failed to generate upload URL",
"error": "Internal Server Error"
}
Response
200 - application/json
The response is of type object.