Generate signed URL for release form upload

curl --request GET \
  --url https://sandbox.theary.ai/files/release-form/generate-upload-url \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://sandbox.theary.ai/files/release-form/generate-upload-url"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://sandbox.theary.ai/files/release-form/generate-upload-url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.theary.ai/files/release-form/generate-upload-url",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.theary.ai/files/release-form/generate-upload-url"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://sandbox.theary.ai/files/release-form/generate-upload-url")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.theary.ai/files/release-form/generate-upload-url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "statusCode": 401,
  "message": "Unauthorized"
}

GET

files

release-form

generate-upload-url

Generate signed URL for release form upload

curl --request GET \
  --url https://sandbox.theary.ai/files/release-form/generate-upload-url \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://sandbox.theary.ai/files/release-form/generate-upload-url"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://sandbox.theary.ai/files/release-form/generate-upload-url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://sandbox.theary.ai/files/release-form/generate-upload-url",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.theary.ai/files/release-form/generate-upload-url"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://sandbox.theary.ai/files/release-form/generate-upload-url")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandbox.theary.ai/files/release-form/generate-upload-url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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 the fileUri 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 signedReleaseFileUrl applies 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"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Response

200 - application/json

The response is of type object.

Submit Inbound Notification List Closeout Events

Overview

Orders API

Search Management

Batches API

Inbound API

Files API

Closeout Events API

Request and order schemas

Webhook schemas

Generate Upload URL

Generate Release Form Upload URL

Authentication

Response

Example Request

Example Response

Uploading the File

Using the File URI

File Storage

Important Notes

Response Codes

Error Responses

Authorizations

Response

​Generate Release Form Upload URL

​Authentication

​Response

​Example Request

​Example Response

​Uploading the File

​Using the File URI

​File Storage

​Important Notes

​Response Codes

​Error Responses

Authorizations

Response

Generate Release Form Upload URL

Authentication

Response

Example Request

Example Response

Uploading the File

Using the File URI

File Storage

Important Notes

Response Codes

Error Responses