Skip to main content

​
Get started with Tavrn’s Demand Letter API

Tavrn’s Demand Letter API provides a simple way for developers to automate the creation of personalized demand letters using Tavrn’s advanced AI capabilities.

​
Step 1: Create an API key

To get started, you will need to create an API key in your organization’s Tavrn dashboard. API keys are used to authenticate requests to the API. All requests to the API must include your API key in an Authorization HTTP header as follows: 
Authorization: Bearer TAVRN_API_KEY

​
Step 2: Creating a job

To create a demand letter job, you need to send a POST request to the /v1/jobs endpoint with the patient’s name, injury date, and any additional information. If no additional information is provided, pass an empty string. 
curl --request POST \
  --url https://demands-api.tavrn.ai/v1/jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "patientName": "<string>",
    "injuryDate": "<string>",
    "additionalInformation": "<string>"
  }'
This will return a packageId which will be used in subsequent steps.

​
Step 3: Uploading files

To upload files for the job, send a POST request to the /v1/jobs/:packageId/upload endpoint with the file and specify its type. Replace :packageId with the actual packageId received from the previous step. Each file must be uploaded individually with its associated type field, which can be medical-record, case-info, or sample-demand. 
curl --request POST \
  --url https://demands-api.tavrn.ai/v1/jobs/<packageId>/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@path/to/your/file.pdf' \
  --form 'type=<type>'
Replace <type> with one of the allowed types: medical-record, case-info, or sample-demand. You can upload multiple files by making separate POST requests for each file.

​
Step 4: Completing the job

To process the uploaded files and complete the job, send a POST request to the /v1/jobs/:packageId/complete endpoint to confirm that all files have been uploaded. 
curl --request POST \
  --url https://demands-api.tavrn.ai/v1/jobs/<packageId>/complete \
  --header 'Authorization: Bearer <token>'

​
Step 5: Fetching the job status

To fetch the status of the job, you can use the status endpoint with the packageId. 
curl --request GET \
  --url https://demands-api.tavrn.ai/v1/jobs/<packageId>/status \
  --header 'Authorization: Bearer <token>'
The status endpoint will return the status of the job, which can be created, processing, done, or failed. If the status is processing, you need to keep polling the status endpoint until the status changes to done or failed. Keep in mind that the processing time can vary depending on the number of files and their size.

​
Step 6: Downloading the demand letter

Once the job is done and has a status of done, you can download the demand letter in PDF using the download endpoint. 
curl --request GET \
  --url https://demands-api.tavrn.ai/v1/jobs/<packageId>/download \
  --header 'Authorization: Bearer <token>'
This will return a secure, pre-signed S3 URL (valid for 1 hour) containing the demand letter in PDF. To download it in DOCX format, use the downloadDocx endpoint.

​
Step 7: Adding New Files and Rerunning the Job

Even after a job has been completed and has a status of done, you can still add new files to the existing package and rerun the job to include all files—both existing and new—in the demand letter.

​
Uploading Additional Files

To add new files to a completed job, use the same upload endpoint as before: 
curl --request POST \
  --url https://demands-api.tavrn.ai/v1/jobs/<packageId>/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=@path/to/your/newfile.pdf' \
  --form 'type=<type>'
Replace <type> with one of the allowed types: medical-record, case-info, or sample-demand.

​
Reprocessing the Job

After uploading the new files, you need to complete the job again to process all the files, including the newly added ones: 
curl --request POST \
  --url https://demands-api.tavrn.ai/v1/jobs/<packageId>/complete \
  --header 'Authorization: Bearer <token>'

​
Additional Endpoints

​
Listing all job IDs for the organization

To list all job IDs for the organization, use the following endpoint: 
curl --request GET \
  --url https://demands-api.tavrn.ai/v1/jobs \
  --header 'Authorization: Bearer <token>'

​
Fetching all files for a job

To fetch all files for a specific job, use the following endpoint: 
curl --request GET \
  --url https://demands-api.tavrn.ai/v1/jobs/<packageId>/files \
  --header 'Authorization: Bearer <token>'
You have successfully created and managed a demand letter job using Tavrn’s Demand Letter API.