{"openapi":"3.1.0","info":{"title":"Send letter API","description":"Send letter handlers","version":"v0.0.1"},"servers":[{"url":"http://localhost","description":"Generated server url"}],"paths":{"/letters/{id}/mark-posted":{"put":{"tags":["action-controller"],"summary":"Mark letter as posted by letter ID","operationId":"markAsPosted","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"time","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/letters/{id}/mark-posted-locally":{"put":{"tags":["action-controller"],"summary":"Mark letter as posted locally by letter ID","operationId":"markAsPostedLocally","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}}},"/letters/{id}/mark-not-sent":{"put":{"tags":["action-controller"],"summary":"Mark stale letter as not sent by ID","operationId":"markAsNotSent","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}}},"/letters/{id}/mark-created":{"put":{"tags":["action-controller"],"summary":"Mark stale letter as created by letter ID","operationId":"markAsCreated","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}}},"/letters/{id}/mark-aborted":{"put":{"tags":["action-controller"],"summary":"Mark letter as aborted by letter ID","operationId":"markAsAborted","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"}}}},"/tasks/process-reports":{"post":{"tags":["task-controller"],"operationId":"processReports","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/letters":{"get":{"tags":["letter-list-controller"],"operationId":"getLetters","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/LettersInfoResponse"}}}}}},"post":{"tags":["send-letter-controller"],"description":"Send letter to print and post service","operationId":"sendLetter","parameters":[{"name":"ServiceAuthorization","in":"header","required":false,"schema":{"type":"string"}},{"name":"isAsync","in":"query","required":false,"schema":{"type":"string","default":"false"}}],"requestBody":{"content":{"application/vnd.uk.gov.hmcts.letter-service.in.letter.v3+json":{"schema":{"$ref":"#/components/schemas/LetterWithPdfsAndNumberOfCopiesRequest"}},"application/vnd.uk.gov.hmcts.letter-service.in.letter.v2+json":{"schema":{"$ref":"#/components/schemas/LetterWithPdfsRequest"}}},"required":true},"responses":{"200":{"description":"Successfully sent letter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendLetterResponse"}}}},"401":{"description":"Invalid service authorisation header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendLetterResponse"}}}},"403":{"description":"Service not configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendLetterResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendLetterResponse"}}}}}}},"/tasks/processed-reports":{"get":{"tags":["task-controller"],"operationId":"retrieveReports","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string"}},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PostedReportTaskResponse"}}}}}}}},"/tasks/check-posted":{"get":{"tags":["task-controller"],"operationId":"checkPosted","parameters":[{"name":"Authorization","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CheckPostedTaskResponse"}}}}}}},"/stale-letters":{"get":{"tags":["stale-letter-controller"],"description":"Retrieves stale letters","operationId":"getStaleLetters","responses":{"200":{"description":"Retrieved stale letters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaleLetterResponse"}}}},"500":{"description":"Error occurred while retrieving stale letters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StaleLetterResponse"}}}}}}},"/stale-letters/download":{"get":{"tags":["stale-letter-controller"],"description":"Downloads file with stale letters","operationId":"getFileWithStaleLetters","responses":{"200":{"description":"Retrieved stale letters file","content":{"application/octet-stream":{"schema":{"$ref":"#/components/schemas/StaleLetterResponse"}}}},"500":{"description":"Error occurred while retrieving stale letters file","content":{"application/octet-stream":{"schema":{"type":"string","format":"byte"}}}}}}},"/reports/count-summary":{"get":{"tags":["reports-controller"],"description":"Retrieves uploaded letters count summary report","operationId":"getCountSummary","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Successfully generated csv report","content":{"application/octet-stream":{"schema":{"$ref":"#/components/schemas/SendLetterResponse"}}}},"500":{"description":"Error occurred while generating csv report","content":{"application/octet-stream":{"schema":{"type":"string","format":"byte"}}}}}}},"/reports/check-reports":{"get":{"tags":["reports-controller"],"description":"Checks if all reports for a date range are present","operationId":"checkReports","parameters":[{"name":"startDate","in":"query","required":false,"schema":{"type":"string","format":"date","default":"2026-06-03"}},{"name":"endDate","in":"query","required":false,"schema":{"type":"string","format":"date","default":"2026-06-09"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MissingReportsResponse"}}}}}}}},"/pending-letters":{"get":{"tags":["pending-letters-controller"],"description":"Retrieves letters that were not uploaded to SFTP yet.","operationId":"getPendingLetters","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PendingLettersResponse"}}}}}}},"/letters/{id}":{"get":{"tags":["send-letter-controller"],"description":"Get letter status","operationId":"getLetterStatus","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"include-additional-info","in":"query","required":false,"schema":{"type":"string","default":"false"}},{"name":"check-duplicate","in":"query","required":false,"schema":{"type":"string","default":"false"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendLetterResponse"}}}},"404":{"description":"Letter not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterStatus"}}}}}}},"/letters/{id}/extended-status":{"get":{"tags":["send-letter-controller"],"description":"Get extended letter status","operationId":"getExtendedLetterStatus","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"include-additional-info","in":"query","required":false,"schema":{"type":"string","default":"false"}},{"name":"check-duplicate","in":"query","required":false,"schema":{"type":"string","default":"false"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendLetterResponse"}}}},"404":{"description":"Letter not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterStatus"}}}}}}},"/letters/v2/{id}":{"get":{"tags":["send-letter-controller"],"description":"Get letter status with copies requested","operationId":"getLatestLetterStatus","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendLetterResponse"}}}},"404":{"description":"Letter not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterStatusV2"}}}}}}},"/feature-flags/{flag}":{"get":{"tags":["feature-flag-controller"],"operationId":"flagStatus","parameters":[{"name":"flag","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"Doc":{"type":"object","properties":{"content":{"type":"string","format":"byte","minLength":1},"copies":{"type":"integer","format":"int32","maximum":100,"minimum":1}},"required":["content"]},"LetterWithPdfsAndNumberOfCopiesRequest":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/Doc"},"maxItems":30,"minItems":1},"type":{"type":"string","description":"Type to be used to print documents","minLength":1},"additional_data":{"type":"object","additionalProperties":{},"writeOnly":true},"additionalData":{"type":"object","additionalProperties":{},"description":"Optional field where services can store any additional information about the letter"}},"required":["type"]},"SendLetterResponse":{"type":"object","properties":{"Letter Id":{"type":"string","format":"uuid","description":"Id of the letter sent to print"}}},"LetterWithPdfsRequest":{"type":"object","description":"Letter consisting of documents and type","properties":{"documents":{"type":"array","description":"List of base64 encoded pdfs to be printed. Maximum allowed is 30","items":{"type":"string","format":"byte"},"maxItems":30,"minItems":1},"type":{"type":"string","description":"Type to be used to print documents","minLength":1},"additional_data":{"type":"object","additionalProperties":{},"description":"Optional field where services can store any additional information about the letter"}},"required":["documents","type"]},"PostedReportTaskResponse":{"type":"object","properties":{"reportCode":{"type":"string"},"reportDate":{"type":"string","format":"date"},"markedPostedCount":{"type":"integer","format":"int64"},"processingFailed":{"type":"boolean"},"errorMessage":{"type":"string"},"international":{"type":"boolean"}}},"CheckPostedTaskResponse":{"type":"object","properties":{"markedNoReportAbortedCount":{"type":"integer","format":"int32"}}},"StaleLetter":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"service":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"sent_to_print_at":{"type":"string","format":"date-time"}}},"StaleLetterResponse":{"type":"object","properties":{"count":{"type":"integer","format":"int32"},"stale_letters":{"type":"array","items":{"$ref":"#/components/schemas/StaleLetter"}}}},"MissingReportsResponse":{"type":"object","properties":{"service_name":{"type":"string"},"is_international":{"type":"boolean"},"report_date":{"type":"string","format":"date"}}},"PendingLetter":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"service":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"key_fingerprint":{"type":"string"}}},"PendingLettersResponse":{"type":"object","properties":{"pending_letters":{"type":"array","items":{"$ref":"#/components/schemas/PendingLetter"}}}},"LetterInfo":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"service":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"sent_to_print_at":{"type":"string","format":"date-time"},"printed_at":{"type":"string","format":"date-time"}}},"LettersInfoResponse":{"type":"object","properties":{"count":{"type":"integer","format":"int32"},"letters":{"type":"array","items":{"$ref":"#/components/schemas/LetterInfo"}}}},"LetterStatus":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"message_id":{"type":"string","description":"This field is deprecated, please use `checksum` instead"},"checksum":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"sent_to_print_at":{"type":"string","format":"date-time"},"printed_at":{"type":"string","format":"date-time"},"additional_data":{"type":"object","additionalProperties":{},"description":"Additional information about the letter"},"copies":{"type":"integer","format":"int32"}}},"LetterStatusV2":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"message_id":{"type":"string","description":"This field is deprecated, please use `checksum` instead"},"checksum":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"sent_to_print_at":{"type":"string","format":"date-time"},"printed_at":{"type":"string","format":"date-time"},"additional_data":{"type":"object","additionalProperties":{},"description":"Additional information about the letter"},"copies":{"type":"object","additionalProperties":{}}}}}}}