Documents
View as MarkdownDocuments store issued records and optional attachments for athletes, coaches, staff, or parents.
On this page
- The document object
- List documentsGET
/api/v1/documents - Retrieve a documentGET
/api/v1/documents/{id} - Create a documentPOST
/api/v1/documents - Update a documentPATCH / PUT / POST
/api/v1/documents/{id} - Delete a documentDELETE
/api/v1/documents/{id}POST/api/v1/documents/{id}/delete - Get a document download URLGET
/api/v1/documents/{id}/download - Remove the attached filePOST
/api/v1/documents/removeFile
Documents store issued records and optional attachments for athletes, coaches, staff, or parents.
Attributes
idinteger- Identifier assigned by the API.
sport_idinteger- ID of the sport.
namestring- Display name of the record.
belongs_tostring- Subject type. Use athlete, coach, staff, or parent.
belongs_obj_idinteger- ID of the subject named by belongs_to.
doc_numberstring- Document number, up to 50 characters.
released_atinteger- Issue date, as Unix seconds or an ISO date.
expires_atinteger- Expiration date, as Unix seconds or an ISO date.
got_paperinteger- Whether the club received a paper copy.
notesstring or null- Notes, up to 200 characters.
is_medicalinteger- 1 for a medical certificate or 0 for another type of document.
typestring or null- Document category.
urlstring or null- URL for an already-uploaded attachment.
filetypestring or null- MIME type of the attachment.
filesizeinteger or null- Attachment size in bytes.
tscinteger or null- Creation time as a Unix timestamp in seconds.
tsuinteger or null- Last update time as a Unix timestamp in seconds.
/api/v1/documentsLists document records in the workspace.
Permissions
Send your API key in X-API-Key. Required permissions are Documents → Read.
Headers
X-Sport-Idinteger- Use the sport ID to limit the response to one sport.
Query parameters
athlete_idinteger- ID of the athlete in the selected sport.
expand_athleteinteger- Use 1 to include the related athlete when available.
qstring- Search document names and any expanded recipient names.
lengthinteger- Number of records to return.
startinteger- Zero-based offset.
drawstring- Optional request marker echoed in the response.
sortstring- Sort by id, name, belongs_to, belongs_obj_id, released_at, expires_at, got_paper, is_agonistic, filetype, filesize, url, tsc, or tsu. Prefix the field name with a minus sign for descending order.
orderstring- Direction for unprefixed sort fields. Use asc or desc.
coach_idinteger- Filter by coach when context is coach_detail.
contextstring- Use coach_detail with coach_id. Aliases view_context and page_context.
staff_idinteger- Filter by staff member.
expand_recipientinteger- Use 1 to include the recipient's name as recipient_fullname.
Returns
Returns records in data, counts before and after text search, and the echoed draw marker.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
/api/v1/documents/{id}Returns one document by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Documents → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the document.
Query parameters
expand_athleteinteger- Use 1 to include the related athlete when available.
Returns
The document is returned in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
/api/v1/documentsCreates a document.
Permissions
Send your API key in X-API-Key. Required permissions are Documents → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Body parameters
namestring- Display name, up to 50 characters. Defaults to Document on creation.
belongs_tostring- Subject type. Use athlete, coach, staff, or parent.
belongs_obj_idinteger- ID of the subject named by belongs_to.
athlete_idinteger- ID of the athlete in the selected sport.
coach_idinteger- Assign the document to this coach.
staff_idinteger- Assign the document to this staff member.
doc_numberstringRequired- Document number, up to 50 characters.
released_atinteger or date stringRequired- Issue date, as Unix seconds or an ISO date.
expires_atinteger or date stringRequired- Expiration date, as Unix seconds or an ISO date.
got_paperboolean- Whether the club received a paper copy.
notesstring or null- Notes, up to 200 characters.
typestring or null- Document category, up to 20 characters.
urlstring or null- URL for an already-uploaded attachment.
filetypestring or null- MIME type of the attachment.
filesizeinteger or null- Attachment size in bytes.
Supply one subject ID such as athlete_id, or send both belongs_to and belongs_obj_id.
Returns
The created document is returned in data.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
409- The file is still processing.
422- One or more fields failed validation.
500- The record or attachment association could not be saved.
/api/v1/documents/{id}Updates a document by ID.
Permissions
Send your API key in X-API-Key. Required permissions are Documents → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the document.
Body parameters
namestring- Display name, up to 50 characters. Defaults to Document on creation.
belongs_tostring- Subject type. Use athlete, coach, staff, or parent.
belongs_obj_idinteger- ID of the subject named by belongs_to.
athlete_idinteger- ID of the athlete in the selected sport.
coach_idinteger- Assign the document to this coach.
staff_idinteger- Assign the document to this staff member.
doc_numberstring- Document number, up to 50 characters.
released_atinteger or date string- Issue date, as Unix seconds or an ISO date.
expires_atinteger or date string- Expiration date, as Unix seconds or an ISO date.
got_paperboolean- Whether the club received a paper copy.
notesstring or null- Notes, up to 200 characters.
typestring or null- Document category, up to 20 characters.
urlstring or null- URL for an already-uploaded attachment.
filetypestring or null- MIME type of the attachment.
filesizeinteger or null- Attachment size in bytes.
Omitted fields keep their stored value. Use the remove-file endpoint to detach an existing attachment.
Returns
Returns a successful update response.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
409- The file is still processing.
422- One or more fields failed validation.
500- The record or attachment association could not be saved.
/api/v1/documents/{id}/api/v1/documents/{id}/deleteRemoves a document.
Permissions
Send your API key in X-API-Key. Required permissions are Documents → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the document.
Returns
Returns a successful removal response.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The requested record was not found.
400- The record could not be removed.
/api/v1/documents/{id}/downloadReturns the URL of a document's attachment. Use the returned URL to fetch the file.
Permissions
Send your API key in X-API-Key. Required permissions are Documents → Read.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Path parameters
idintegerRequired- ID of the document.
Returns
Returns the record in item and the file URL in url. A protected file may have a temporary URL.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
404- The document or its attachment was not found.
400- The URL could not be prepared.
/api/v1/documents/removeFileRemoves the attachment while preserving the record.
Permissions
Send your API key in X-API-Key. Required permissions are Documents → Write.
Headers
X-Sport-IdintegerRequired- The sport ID from List sports. Use the sport the record belongs to.
Body parameters
idintegerRequired- ID of the record. Send as a URL-encoded form field.
Returns
Returns confirmation that the attachment was removed.
Errors
401- The API key is missing or invalid.
403- The API key lacks the required permission.
400- There is no attachment or it could not be removed.
404- The requested record was not found.