> For the complete documentation index, see [llms.txt](https://docs.welkinhealth.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.welkinhealth.com/api-reference/fax.md).

# Fax

Requests for working with faxes. Most requests require a fax ID, which you can obtain from the Create Draft Fax response or the Get all Faxes response.

To send a fax via the API:

1. Create Draft Fax — the response returns the draft ID required for all subsequent actions.
2. Optionally use Update Fax to edit the draft before sending.
3. Upload files to the fax draft.
4. Optionally use Assign Fax to associate a patient with the fax.
5. Send Draft Fax to dispatch it.

## Get all Faxes

> Get a list of all fax numbers in the env

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Fax","description":"Requests for working with faxes. Most requests require a fax ID, which you can obtain from the [Create Draft Fax](#post-tenantname-instancename-faxes) response or the [Get all Faxes](#get-tenantname-instancename-faxes) response.\n\nTo send a fax via the API:\n\n1. [Create Draft Fax](#post-tenantname-instancename-faxes) — the response returns the draft ID required for all subsequent actions.\n2. Optionally use [Update Fax](#patch-tenantname-instancename-faxes-faxid) to edit the draft before sending.\n3. [Upload files](#post-tenantname-instancename-faxes-faxid-files) to the fax draft.\n4. Optionally use [Assign Fax](#post-tenantname-instancename-faxes-faxid-assign) to associate a patient with the fax.\n5. [Send Draft Fax](#post-tenantname-instancename-faxes-faxid-send) to dispatch it."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"FaxListResponse":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/Fax"}}}}]},"PaginatedResponse":{"type":"object","description":"Standard paginated response wrapper.","properties":{"content":{"type":"array","items":{"type":"object"}},"pageable":{"$ref":"#/components/schemas/PageableInfo"},"totalElements":{"type":"integer","description":"Total number of matching records"},"totalPages":{"type":"integer","description":"Total number of pages"},"last":{"type":"boolean"},"first":{"type":"boolean"},"number":{"type":"integer","description":"Current page number (zero-based)"},"size":{"type":"integer","description":"Page size"},"numberOfElements":{"type":"integer","description":"Number of elements on the current page"},"empty":{"type":"boolean"},"sort":{"$ref":"#/components/schemas/SortInfo"}}},"PageableInfo":{"type":"object","properties":{"sort":{"$ref":"#/components/schemas/SortInfo"},"pageSize":{"type":"integer"},"pageNumber":{"type":"integer"},"offset":{"type":"integer"},"unpaged":{"type":"boolean"},"paged":{"type":"boolean"}}},"SortInfo":{"type":"object","properties":{"sorted":{"type":"boolean"},"unsorted":{"type":"boolean"},"empty":{"type":"boolean"}}},"Fax":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"updatedBy":{"type":"string","format":"uuid","nullable":true},"createdByName":{"type":"string"},"updatedByName":{"type":"string"},"faxId":{"type":"string","nullable":true,"description":"External fax provider ID"},"externalId":{"type":"string","format":"uuid","nullable":true},"direction":{"type":"string","enum":["IN","OUT"]},"fromNumber":{"type":"string","description":"E.164 format"},"sender":{"$ref":"#/components/schemas/FaxParty"},"toNumber":{"type":"string","nullable":true,"description":"E.164 format"},"receiver":{"$ref":"#/components/schemas/FaxParty","nullable":true},"subject":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","PROCESSING","DELIVERED","FAILED"]},"originalStatus":{"type":"string","nullable":true,"description":"Raw status string from the fax provider"},"statusMessage":{"type":"string","nullable":true},"document":{"$ref":"#/components/schemas/FaxDocument"},"patient":{"$ref":"#/components/schemas/FaxPatient"},"receivedAt":{"type":"string","format":"date-time","nullable":true},"highQuality":{"type":"boolean"},"files":{"type":"array","items":{"$ref":"#/components/schemas/FaxFile"}},"sentBy":{"type":"string","format":"uuid","nullable":true},"sentByName":{"type":"string","nullable":true},"reviewed":{"type":"boolean"}}},"FaxParty":{"type":"object","description":"Sender or receiver of a fax.","required":["type","faxNumber"],"properties":{"type":{"type":"string","enum":["FAX_NUMBER","SYSTEM_FAX_NUMBER"],"description":"`FAX_NUMBER` for external parties, `SYSTEM_FAX_NUMBER` for Welkin system numbers"},"faxNumber":{"type":"string","description":"E.164 format"}}},"FaxDocument":{"type":"object","nullable":true,"description":"Document record linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"title":{"type":"string"}}},"FaxPatient":{"type":"object","nullable":true,"description":"Patient linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"FaxFile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"size":{"type":"integer","description":"File size in bytes"},"contentType":{"type":"string"},"storageKey":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/faxes":{"get":{"summary":"Get all Faxes","tags":["Fax"],"operationId":"Get_all_Faxes","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"name":"statuses","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"multivalue"},{"name":"direction","in":"query","required":false,"schema":{"type":"string"},"description":"IN or OUT"},{"name":"subject","in":"query","required":false,"schema":{"type":"string"},"description":"Fax Subject"},{"name":"fromNumber","in":"query","required":false,"schema":{"type":"string"},"description":"A phone number without a plus sign at the beginning"},{"name":"toNumber","in":"query","required":false,"schema":{"type":"string"},"description":"A phone number without a plus sign at the beginning"},{"name":"patientId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"The patient uuid associated with the fax"},{"name":"reviewed","in":"query","required":false,"schema":{"type":"boolean"},"description":"true or false"},{"name":"sentByName","in":"query","required":false,"schema":{"type":"string"},"description":"The name of the user who sent the fax"},{"name":"sentBy","in":"query","required":false,"schema":{"type":"string"},"description":"The id of the user who sent the fax"},{"name":"createdAtBefore","in":"query","required":false,"schema":{"type":"string"}},{"name":"createdAtAfter","in":"query","required":false,"schema":{"type":"string"}},{"name":"receivedAtBefore","in":"query","required":false,"schema":{"type":"string"}},{"name":"receivedAtAfter","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of faxes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FaxListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Get a list of all fax numbers in the env"}}}}
```

## Create Draft Fax

> Request to create a fax draft. The response will return the draft ID, which is required for subsequent requests to perform actions on this draft

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Fax","description":"Requests for working with faxes. Most requests require a fax ID, which you can obtain from the [Create Draft Fax](#post-tenantname-instancename-faxes) response or the [Get all Faxes](#get-tenantname-instancename-faxes) response.\n\nTo send a fax via the API:\n\n1. [Create Draft Fax](#post-tenantname-instancename-faxes) — the response returns the draft ID required for all subsequent actions.\n2. Optionally use [Update Fax](#patch-tenantname-instancename-faxes-faxid) to edit the draft before sending.\n3. [Upload files](#post-tenantname-instancename-faxes-faxid-files) to the fax draft.\n4. Optionally use [Assign Fax](#post-tenantname-instancename-faxes-faxid-assign) to associate a patient with the fax.\n5. [Send Draft Fax](#post-tenantname-instancename-faxes-faxid-send) to dispatch it."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}}},"schemas":{"Fax":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"updatedBy":{"type":"string","format":"uuid","nullable":true},"createdByName":{"type":"string"},"updatedByName":{"type":"string"},"faxId":{"type":"string","nullable":true,"description":"External fax provider ID"},"externalId":{"type":"string","format":"uuid","nullable":true},"direction":{"type":"string","enum":["IN","OUT"]},"fromNumber":{"type":"string","description":"E.164 format"},"sender":{"$ref":"#/components/schemas/FaxParty"},"toNumber":{"type":"string","nullable":true,"description":"E.164 format"},"receiver":{"$ref":"#/components/schemas/FaxParty","nullable":true},"subject":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","PROCESSING","DELIVERED","FAILED"]},"originalStatus":{"type":"string","nullable":true,"description":"Raw status string from the fax provider"},"statusMessage":{"type":"string","nullable":true},"document":{"$ref":"#/components/schemas/FaxDocument"},"patient":{"$ref":"#/components/schemas/FaxPatient"},"receivedAt":{"type":"string","format":"date-time","nullable":true},"highQuality":{"type":"boolean"},"files":{"type":"array","items":{"$ref":"#/components/schemas/FaxFile"}},"sentBy":{"type":"string","format":"uuid","nullable":true},"sentByName":{"type":"string","nullable":true},"reviewed":{"type":"boolean"}}},"FaxParty":{"type":"object","description":"Sender or receiver of a fax.","required":["type","faxNumber"],"properties":{"type":{"type":"string","enum":["FAX_NUMBER","SYSTEM_FAX_NUMBER"],"description":"`FAX_NUMBER` for external parties, `SYSTEM_FAX_NUMBER` for Welkin system numbers"},"faxNumber":{"type":"string","description":"E.164 format"}}},"FaxDocument":{"type":"object","nullable":true,"description":"Document record linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"title":{"type":"string"}}},"FaxPatient":{"type":"object","nullable":true,"description":"Patient linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"FaxFile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"size":{"type":"integer","description":"File size in bytes"},"contentType":{"type":"string"},"storageKey":{"type":"string"}}},"CreateFaxRequest":{"type":"object","required":["sender","receiver"],"properties":{"sender":{"$ref":"#/components/schemas/FaxParty"},"receiver":{"$ref":"#/components/schemas/FaxParty"},"subject":{"type":"string","nullable":true},"highQuality":{"type":"boolean","default":false},"patientId":{"type":"string","format":"uuid","nullable":true}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/faxes":{"post":{"summary":"Create Draft Fax","tags":["Fax"],"operationId":"Create_Draft_Fax","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"}],"responses":{"201":{"description":"Fax draft created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fax"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Request to create a fax draft. The response will return the draft ID, which is required for subsequent requests to perform actions on this draft","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFaxRequest"}}}}}}}}
```

## Get Fax by ID

> Allows you to find a specific fax

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Fax","description":"Requests for working with faxes. Most requests require a fax ID, which you can obtain from the [Create Draft Fax](#post-tenantname-instancename-faxes) response or the [Get all Faxes](#get-tenantname-instancename-faxes) response.\n\nTo send a fax via the API:\n\n1. [Create Draft Fax](#post-tenantname-instancename-faxes) — the response returns the draft ID required for all subsequent actions.\n2. Optionally use [Update Fax](#patch-tenantname-instancename-faxes-faxid) to edit the draft before sending.\n3. [Upload files](#post-tenantname-instancename-faxes-faxid-files) to the fax draft.\n4. Optionally use [Assign Fax](#post-tenantname-instancename-faxes-faxid-assign) to associate a patient with the fax.\n5. [Send Draft Fax](#post-tenantname-instancename-faxes-faxid-send) to dispatch it."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"FaxId":{"name":"faxId","in":"path","required":true,"description":"UUID of the fax","schema":{"type":"string","format":"uuid"}}},"schemas":{"Fax":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"updatedBy":{"type":"string","format":"uuid","nullable":true},"createdByName":{"type":"string"},"updatedByName":{"type":"string"},"faxId":{"type":"string","nullable":true,"description":"External fax provider ID"},"externalId":{"type":"string","format":"uuid","nullable":true},"direction":{"type":"string","enum":["IN","OUT"]},"fromNumber":{"type":"string","description":"E.164 format"},"sender":{"$ref":"#/components/schemas/FaxParty"},"toNumber":{"type":"string","nullable":true,"description":"E.164 format"},"receiver":{"$ref":"#/components/schemas/FaxParty","nullable":true},"subject":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","PROCESSING","DELIVERED","FAILED"]},"originalStatus":{"type":"string","nullable":true,"description":"Raw status string from the fax provider"},"statusMessage":{"type":"string","nullable":true},"document":{"$ref":"#/components/schemas/FaxDocument"},"patient":{"$ref":"#/components/schemas/FaxPatient"},"receivedAt":{"type":"string","format":"date-time","nullable":true},"highQuality":{"type":"boolean"},"files":{"type":"array","items":{"$ref":"#/components/schemas/FaxFile"}},"sentBy":{"type":"string","format":"uuid","nullable":true},"sentByName":{"type":"string","nullable":true},"reviewed":{"type":"boolean"}}},"FaxParty":{"type":"object","description":"Sender or receiver of a fax.","required":["type","faxNumber"],"properties":{"type":{"type":"string","enum":["FAX_NUMBER","SYSTEM_FAX_NUMBER"],"description":"`FAX_NUMBER` for external parties, `SYSTEM_FAX_NUMBER` for Welkin system numbers"},"faxNumber":{"type":"string","description":"E.164 format"}}},"FaxDocument":{"type":"object","nullable":true,"description":"Document record linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"title":{"type":"string"}}},"FaxPatient":{"type":"object","nullable":true,"description":"Patient linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"FaxFile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"size":{"type":"integer","description":"File size in bytes"},"contentType":{"type":"string"},"storageKey":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/faxes/{faxId}":{"get":{"summary":"Get Fax by ID","tags":["Fax"],"operationId":"Get_Fax_by_ID","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/FaxId"}],"responses":{"200":{"description":"Fax record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fax"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Allows you to find a specific fax"}}}}
```

## Delete Fax

> Delete the fax with the specified ID

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Fax","description":"Requests for working with faxes. Most requests require a fax ID, which you can obtain from the [Create Draft Fax](#post-tenantname-instancename-faxes) response or the [Get all Faxes](#get-tenantname-instancename-faxes) response.\n\nTo send a fax via the API:\n\n1. [Create Draft Fax](#post-tenantname-instancename-faxes) — the response returns the draft ID required for all subsequent actions.\n2. Optionally use [Update Fax](#patch-tenantname-instancename-faxes-faxid) to edit the draft before sending.\n3. [Upload files](#post-tenantname-instancename-faxes-faxid-files) to the fax draft.\n4. Optionally use [Assign Fax](#post-tenantname-instancename-faxes-faxid-assign) to associate a patient with the fax.\n5. [Send Draft Fax](#post-tenantname-instancename-faxes-faxid-send) to dispatch it."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"FaxId":{"name":"faxId","in":"path","required":true,"description":"UUID of the fax","schema":{"type":"string","format":"uuid"}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/faxes/{faxId}":{"delete":{"summary":"Delete Fax","tags":["Fax"],"operationId":"Delete_Fax","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/FaxId"}],"responses":{"200":{"description":"Fax deleted"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Delete the fax with the specified ID"}}}}
```

## Update Fax

> Request to update faxes.\
> \
> This request allows you to edit a fax \_draft\_ before sending it. You can retrieve the fax ID from the response to a fax draft creation request or from a fax list request.\
> \
> You can also use this request to mark an \_incoming fax as reviewed\_. To do this, set the “reviewed” parameter as true in the request body:  \
> \`{\`\
> \
> \`"reviewed": true\`\
> \
> \`}\`  \
> This will only work for incoming faxes.\
> \
> For \_outgoing\_ faxes, you can also update the patient in this request. To do so, include the following in the body:  \
> \`"patientId": {{patientId}}\`

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Fax","description":"Requests for working with faxes. Most requests require a fax ID, which you can obtain from the [Create Draft Fax](#post-tenantname-instancename-faxes) response or the [Get all Faxes](#get-tenantname-instancename-faxes) response.\n\nTo send a fax via the API:\n\n1. [Create Draft Fax](#post-tenantname-instancename-faxes) — the response returns the draft ID required for all subsequent actions.\n2. Optionally use [Update Fax](#patch-tenantname-instancename-faxes-faxid) to edit the draft before sending.\n3. [Upload files](#post-tenantname-instancename-faxes-faxid-files) to the fax draft.\n4. Optionally use [Assign Fax](#post-tenantname-instancename-faxes-faxid-assign) to associate a patient with the fax.\n5. [Send Draft Fax](#post-tenantname-instancename-faxes-faxid-send) to dispatch it."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"FaxId":{"name":"faxId","in":"path","required":true,"description":"UUID of the fax","schema":{"type":"string","format":"uuid"}}},"schemas":{"Fax":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"updatedBy":{"type":"string","format":"uuid","nullable":true},"createdByName":{"type":"string"},"updatedByName":{"type":"string"},"faxId":{"type":"string","nullable":true,"description":"External fax provider ID"},"externalId":{"type":"string","format":"uuid","nullable":true},"direction":{"type":"string","enum":["IN","OUT"]},"fromNumber":{"type":"string","description":"E.164 format"},"sender":{"$ref":"#/components/schemas/FaxParty"},"toNumber":{"type":"string","nullable":true,"description":"E.164 format"},"receiver":{"$ref":"#/components/schemas/FaxParty","nullable":true},"subject":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","PROCESSING","DELIVERED","FAILED"]},"originalStatus":{"type":"string","nullable":true,"description":"Raw status string from the fax provider"},"statusMessage":{"type":"string","nullable":true},"document":{"$ref":"#/components/schemas/FaxDocument"},"patient":{"$ref":"#/components/schemas/FaxPatient"},"receivedAt":{"type":"string","format":"date-time","nullable":true},"highQuality":{"type":"boolean"},"files":{"type":"array","items":{"$ref":"#/components/schemas/FaxFile"}},"sentBy":{"type":"string","format":"uuid","nullable":true},"sentByName":{"type":"string","nullable":true},"reviewed":{"type":"boolean"}}},"FaxParty":{"type":"object","description":"Sender or receiver of a fax.","required":["type","faxNumber"],"properties":{"type":{"type":"string","enum":["FAX_NUMBER","SYSTEM_FAX_NUMBER"],"description":"`FAX_NUMBER` for external parties, `SYSTEM_FAX_NUMBER` for Welkin system numbers"},"faxNumber":{"type":"string","description":"E.164 format"}}},"FaxDocument":{"type":"object","nullable":true,"description":"Document record linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"title":{"type":"string"}}},"FaxPatient":{"type":"object","nullable":true,"description":"Patient linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"FaxFile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"size":{"type":"integer","description":"File size in bytes"},"contentType":{"type":"string"},"storageKey":{"type":"string"}}},"UpdateFaxRequest":{"type":"object","description":"Partial update — all fields optional.","properties":{"receiver":{"$ref":"#/components/schemas/FaxParty"},"subject":{"type":"string","nullable":true},"highQuality":{"type":"boolean"},"patientId":{"type":"string","format":"uuid","description":"For outgoing faxes only."},"reviewed":{"type":"boolean","description":"For incoming faxes only — marks the fax as reviewed."}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/faxes/{faxId}":{"patch":{"summary":"Update Fax","tags":["Fax"],"operationId":"Update_Fax","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/FaxId"}],"responses":{"200":{"description":"Updated fax","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fax"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Request to update faxes.\n\nThis request allows you to edit a fax _draft_ before sending it. You can retrieve the fax ID from the response to a fax draft creation request or from a fax list request.\n\nYou can also use this request to mark an _incoming fax as reviewed_. To do this, set the “reviewed” parameter as true in the request body:  \n`{`\n\n`\"reviewed\": true`\n\n`}`  \nThis will only work for incoming faxes.\n\nFor _outgoing_ faxes, you can also update the patient in this request. To do so, include the following in the body:  \n`\"patientId\": {{patientId}}`","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFaxRequest"}}}}}}}}
```

## Upload files to Draft Fax

> Request to upload files to a fax draft. You can retrieve the fax ID from the response to a fax draft creation request or from a fax list request\
> \
> The response will also include the IDs of the uploaded files — these are required to request file deletion.\
> \
> File extensions: jpg (jpeg), png, pdf, doсx.\
> \
> File size: up to 10 files with a total size of up to 100 MB.

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Fax","description":"Requests for working with faxes. Most requests require a fax ID, which you can obtain from the [Create Draft Fax](#post-tenantname-instancename-faxes) response or the [Get all Faxes](#get-tenantname-instancename-faxes) response.\n\nTo send a fax via the API:\n\n1. [Create Draft Fax](#post-tenantname-instancename-faxes) — the response returns the draft ID required for all subsequent actions.\n2. Optionally use [Update Fax](#patch-tenantname-instancename-faxes-faxid) to edit the draft before sending.\n3. [Upload files](#post-tenantname-instancename-faxes-faxid-files) to the fax draft.\n4. Optionally use [Assign Fax](#post-tenantname-instancename-faxes-faxid-assign) to associate a patient with the fax.\n5. [Send Draft Fax](#post-tenantname-instancename-faxes-faxid-send) to dispatch it."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"FaxId":{"name":"faxId","in":"path","required":true,"description":"UUID of the fax","schema":{"type":"string","format":"uuid"}}},"schemas":{"Fax":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"updatedBy":{"type":"string","format":"uuid","nullable":true},"createdByName":{"type":"string"},"updatedByName":{"type":"string"},"faxId":{"type":"string","nullable":true,"description":"External fax provider ID"},"externalId":{"type":"string","format":"uuid","nullable":true},"direction":{"type":"string","enum":["IN","OUT"]},"fromNumber":{"type":"string","description":"E.164 format"},"sender":{"$ref":"#/components/schemas/FaxParty"},"toNumber":{"type":"string","nullable":true,"description":"E.164 format"},"receiver":{"$ref":"#/components/schemas/FaxParty","nullable":true},"subject":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","PROCESSING","DELIVERED","FAILED"]},"originalStatus":{"type":"string","nullable":true,"description":"Raw status string from the fax provider"},"statusMessage":{"type":"string","nullable":true},"document":{"$ref":"#/components/schemas/FaxDocument"},"patient":{"$ref":"#/components/schemas/FaxPatient"},"receivedAt":{"type":"string","format":"date-time","nullable":true},"highQuality":{"type":"boolean"},"files":{"type":"array","items":{"$ref":"#/components/schemas/FaxFile"}},"sentBy":{"type":"string","format":"uuid","nullable":true},"sentByName":{"type":"string","nullable":true},"reviewed":{"type":"boolean"}}},"FaxParty":{"type":"object","description":"Sender or receiver of a fax.","required":["type","faxNumber"],"properties":{"type":{"type":"string","enum":["FAX_NUMBER","SYSTEM_FAX_NUMBER"],"description":"`FAX_NUMBER` for external parties, `SYSTEM_FAX_NUMBER` for Welkin system numbers"},"faxNumber":{"type":"string","description":"E.164 format"}}},"FaxDocument":{"type":"object","nullable":true,"description":"Document record linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"title":{"type":"string"}}},"FaxPatient":{"type":"object","nullable":true,"description":"Patient linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"FaxFile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"size":{"type":"integer","description":"File size in bytes"},"contentType":{"type":"string"},"storageKey":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/faxes/{faxId}/files":{"post":{"summary":"Upload files to Draft Fax","tags":["Fax"],"operationId":"Upload_files_to_Draft_Fax","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/FaxId"}],"responses":{"200":{"description":"Updated fax with uploaded files","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fax"}}}},"201":{"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Request to upload files to a fax draft. You can retrieve the fax ID from the response to a fax draft creation request or from a fax list request\n\nThe response will also include the IDs of the uploaded files — these are required to request file deletion.\n\nFile extensions: jpg (jpeg), png, pdf, doсx.\n\nFile size: up to 10 files with a total size of up to 100 MB.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"Allowed: jpg, jpeg, png, pdf, docx. Up to 10 files, 100MB total."}}}}}}}}}}
```

## Delete file from Draft Fax

> This request allows you to delete a file from the fax draft. To do this, you must specify the file ID. You can retrieve the file ID from the response to a fax file upload request or from a fax list request

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Fax","description":"Requests for working with faxes. Most requests require a fax ID, which you can obtain from the [Create Draft Fax](#post-tenantname-instancename-faxes) response or the [Get all Faxes](#get-tenantname-instancename-faxes) response.\n\nTo send a fax via the API:\n\n1. [Create Draft Fax](#post-tenantname-instancename-faxes) — the response returns the draft ID required for all subsequent actions.\n2. Optionally use [Update Fax](#patch-tenantname-instancename-faxes-faxid) to edit the draft before sending.\n3. [Upload files](#post-tenantname-instancename-faxes-faxid-files) to the fax draft.\n4. Optionally use [Assign Fax](#post-tenantname-instancename-faxes-faxid-assign) to associate a patient with the fax.\n5. [Send Draft Fax](#post-tenantname-instancename-faxes-faxid-send) to dispatch it."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"FaxId":{"name":"faxId","in":"path","required":true,"description":"UUID of the fax","schema":{"type":"string","format":"uuid"}},"FileId":{"name":"fileId","in":"path","required":true,"description":"UUID of the uploaded file","schema":{"type":"string","format":"uuid"}}},"schemas":{"Fax":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"updatedBy":{"type":"string","format":"uuid","nullable":true},"createdByName":{"type":"string"},"updatedByName":{"type":"string"},"faxId":{"type":"string","nullable":true,"description":"External fax provider ID"},"externalId":{"type":"string","format":"uuid","nullable":true},"direction":{"type":"string","enum":["IN","OUT"]},"fromNumber":{"type":"string","description":"E.164 format"},"sender":{"$ref":"#/components/schemas/FaxParty"},"toNumber":{"type":"string","nullable":true,"description":"E.164 format"},"receiver":{"$ref":"#/components/schemas/FaxParty","nullable":true},"subject":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","PROCESSING","DELIVERED","FAILED"]},"originalStatus":{"type":"string","nullable":true,"description":"Raw status string from the fax provider"},"statusMessage":{"type":"string","nullable":true},"document":{"$ref":"#/components/schemas/FaxDocument"},"patient":{"$ref":"#/components/schemas/FaxPatient"},"receivedAt":{"type":"string","format":"date-time","nullable":true},"highQuality":{"type":"boolean"},"files":{"type":"array","items":{"$ref":"#/components/schemas/FaxFile"}},"sentBy":{"type":"string","format":"uuid","nullable":true},"sentByName":{"type":"string","nullable":true},"reviewed":{"type":"boolean"}}},"FaxParty":{"type":"object","description":"Sender or receiver of a fax.","required":["type","faxNumber"],"properties":{"type":{"type":"string","enum":["FAX_NUMBER","SYSTEM_FAX_NUMBER"],"description":"`FAX_NUMBER` for external parties, `SYSTEM_FAX_NUMBER` for Welkin system numbers"},"faxNumber":{"type":"string","description":"E.164 format"}}},"FaxDocument":{"type":"object","nullable":true,"description":"Document record linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"title":{"type":"string"}}},"FaxPatient":{"type":"object","nullable":true,"description":"Patient linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"FaxFile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"size":{"type":"integer","description":"File size in bytes"},"contentType":{"type":"string"},"storageKey":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/faxes/{faxId}/files/{fileId}":{"delete":{"summary":"Delete file from Draft Fax","tags":["Fax"],"operationId":"Delete_file_from_Draft_Fax","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/FaxId"},{"$ref":"#/components/parameters/FileId"}],"responses":{"200":{"description":"Updated fax with file removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fax"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"This request allows you to delete a file from the fax draft. To do this, you must specify the file ID. You can retrieve the file ID from the response to a fax file upload request or from a fax list request"}}}}
```

## Send Draft Fax

> Send a draft fax with the specified ID. The fax status in the response will be “PROCESSING,” which means the fax is currently being sent.\
> \
> You can retrieve the fax ID from the response to a fax draft creation request or from a fax list request

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Fax","description":"Requests for working with faxes. Most requests require a fax ID, which you can obtain from the [Create Draft Fax](#post-tenantname-instancename-faxes) response or the [Get all Faxes](#get-tenantname-instancename-faxes) response.\n\nTo send a fax via the API:\n\n1. [Create Draft Fax](#post-tenantname-instancename-faxes) — the response returns the draft ID required for all subsequent actions.\n2. Optionally use [Update Fax](#patch-tenantname-instancename-faxes-faxid) to edit the draft before sending.\n3. [Upload files](#post-tenantname-instancename-faxes-faxid-files) to the fax draft.\n4. Optionally use [Assign Fax](#post-tenantname-instancename-faxes-faxid-assign) to associate a patient with the fax.\n5. [Send Draft Fax](#post-tenantname-instancename-faxes-faxid-send) to dispatch it."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"FaxId":{"name":"faxId","in":"path","required":true,"description":"UUID of the fax","schema":{"type":"string","format":"uuid"}}},"schemas":{"Fax":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"updatedBy":{"type":"string","format":"uuid","nullable":true},"createdByName":{"type":"string"},"updatedByName":{"type":"string"},"faxId":{"type":"string","nullable":true,"description":"External fax provider ID"},"externalId":{"type":"string","format":"uuid","nullable":true},"direction":{"type":"string","enum":["IN","OUT"]},"fromNumber":{"type":"string","description":"E.164 format"},"sender":{"$ref":"#/components/schemas/FaxParty"},"toNumber":{"type":"string","nullable":true,"description":"E.164 format"},"receiver":{"$ref":"#/components/schemas/FaxParty","nullable":true},"subject":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","PROCESSING","DELIVERED","FAILED"]},"originalStatus":{"type":"string","nullable":true,"description":"Raw status string from the fax provider"},"statusMessage":{"type":"string","nullable":true},"document":{"$ref":"#/components/schemas/FaxDocument"},"patient":{"$ref":"#/components/schemas/FaxPatient"},"receivedAt":{"type":"string","format":"date-time","nullable":true},"highQuality":{"type":"boolean"},"files":{"type":"array","items":{"$ref":"#/components/schemas/FaxFile"}},"sentBy":{"type":"string","format":"uuid","nullable":true},"sentByName":{"type":"string","nullable":true},"reviewed":{"type":"boolean"}}},"FaxParty":{"type":"object","description":"Sender or receiver of a fax.","required":["type","faxNumber"],"properties":{"type":{"type":"string","enum":["FAX_NUMBER","SYSTEM_FAX_NUMBER"],"description":"`FAX_NUMBER` for external parties, `SYSTEM_FAX_NUMBER` for Welkin system numbers"},"faxNumber":{"type":"string","description":"E.164 format"}}},"FaxDocument":{"type":"object","nullable":true,"description":"Document record linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"title":{"type":"string"}}},"FaxPatient":{"type":"object","nullable":true,"description":"Patient linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"FaxFile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"size":{"type":"integer","description":"File size in bytes"},"contentType":{"type":"string"},"storageKey":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/faxes/{faxId}/send":{"post":{"summary":"Send Draft Fax","tags":["Fax"],"operationId":"Send_Draft_Fax","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/FaxId"}],"responses":{"200":{"description":"Fax queued for sending (status will be PROCESSING)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fax"}}}},"201":{"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Send a draft fax with the specified ID. The fax status in the response will be “PROCESSING,” which means the fax is currently being sent.\n\nYou can retrieve the fax ID from the response to a fax draft creation request or from a fax list request"}}}}
```

## Retry Sending

> If the fax failed to send, you can use this request to retry sending it. You can retrieve the fax ID from the response to a fax draft creation request or from a fax list request

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Fax","description":"Requests for working with faxes. Most requests require a fax ID, which you can obtain from the [Create Draft Fax](#post-tenantname-instancename-faxes) response or the [Get all Faxes](#get-tenantname-instancename-faxes) response.\n\nTo send a fax via the API:\n\n1. [Create Draft Fax](#post-tenantname-instancename-faxes) — the response returns the draft ID required for all subsequent actions.\n2. Optionally use [Update Fax](#patch-tenantname-instancename-faxes-faxid) to edit the draft before sending.\n3. [Upload files](#post-tenantname-instancename-faxes-faxid-files) to the fax draft.\n4. Optionally use [Assign Fax](#post-tenantname-instancename-faxes-faxid-assign) to associate a patient with the fax.\n5. [Send Draft Fax](#post-tenantname-instancename-faxes-faxid-send) to dispatch it."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"FaxId":{"name":"faxId","in":"path","required":true,"description":"UUID of the fax","schema":{"type":"string","format":"uuid"}}},"schemas":{"Fax":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"updatedBy":{"type":"string","format":"uuid","nullable":true},"createdByName":{"type":"string"},"updatedByName":{"type":"string"},"faxId":{"type":"string","nullable":true,"description":"External fax provider ID"},"externalId":{"type":"string","format":"uuid","nullable":true},"direction":{"type":"string","enum":["IN","OUT"]},"fromNumber":{"type":"string","description":"E.164 format"},"sender":{"$ref":"#/components/schemas/FaxParty"},"toNumber":{"type":"string","nullable":true,"description":"E.164 format"},"receiver":{"$ref":"#/components/schemas/FaxParty","nullable":true},"subject":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","PROCESSING","DELIVERED","FAILED"]},"originalStatus":{"type":"string","nullable":true,"description":"Raw status string from the fax provider"},"statusMessage":{"type":"string","nullable":true},"document":{"$ref":"#/components/schemas/FaxDocument"},"patient":{"$ref":"#/components/schemas/FaxPatient"},"receivedAt":{"type":"string","format":"date-time","nullable":true},"highQuality":{"type":"boolean"},"files":{"type":"array","items":{"$ref":"#/components/schemas/FaxFile"}},"sentBy":{"type":"string","format":"uuid","nullable":true},"sentByName":{"type":"string","nullable":true},"reviewed":{"type":"boolean"}}},"FaxParty":{"type":"object","description":"Sender or receiver of a fax.","required":["type","faxNumber"],"properties":{"type":{"type":"string","enum":["FAX_NUMBER","SYSTEM_FAX_NUMBER"],"description":"`FAX_NUMBER` for external parties, `SYSTEM_FAX_NUMBER` for Welkin system numbers"},"faxNumber":{"type":"string","description":"E.164 format"}}},"FaxDocument":{"type":"object","nullable":true,"description":"Document record linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"title":{"type":"string"}}},"FaxPatient":{"type":"object","nullable":true,"description":"Patient linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"FaxFile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"size":{"type":"integer","description":"File size in bytes"},"contentType":{"type":"string"},"storageKey":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/faxes/{faxId}/retry":{"post":{"summary":"Retry Sending","tags":["Fax"],"operationId":"Retry_Sending","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/FaxId"}],"responses":{"200":{"description":"Fax re-queued for sending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fax"}}}},"201":{"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"If the fax failed to send, you can use this request to retry sending it. You can retrieve the fax ID from the response to a fax draft creation request or from a fax list request"}}}}
```

## Assign Fax

> Request to assign a patient to the fax.\
> \
> For an incoming fax, the request body is required to include the patient ID and the document type in which the fax file will be saved.\
> \
> For an outgoing fax, only the patient ID is enough.

```json
{"openapi":"3.0.3","info":{"title":"Welkin Health API","version":"1.0.0"},"tags":[{"name":"Fax","description":"Requests for working with faxes. Most requests require a fax ID, which you can obtain from the [Create Draft Fax](#post-tenantname-instancename-faxes) response or the [Get all Faxes](#get-tenantname-instancename-faxes) response.\n\nTo send a fax via the API:\n\n1. [Create Draft Fax](#post-tenantname-instancename-faxes) — the response returns the draft ID required for all subsequent actions.\n2. Optionally use [Update Fax](#patch-tenantname-instancename-faxes-faxid) to edit the draft before sending.\n3. [Upload files](#post-tenantname-instancename-faxes-faxid-files) to the fax draft.\n4. Optionally use [Assign Fax](#post-tenantname-instancename-faxes-faxid-assign) to associate a patient with the fax.\n5. [Send Draft Fax](#post-tenantname-instancename-faxes-faxid-send) to dispatch it."}],"servers":[{"url":"https://api.live.welkincloud.io","description":"Welkin Health production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token obtained from `POST /{tenantName}/admin/api_clients/{clientName}`. Valid for 60 minutes."}},"parameters":{"TenantName":{"name":"tenantName","in":"path","required":true,"description":"Your organization (tenant) name, e.g. `acme-health`","schema":{"type":"string"}},"InstanceName":{"name":"instanceName","in":"path","required":true,"description":"Your environment name: `live`, `sandbox`, or a custom name","schema":{"type":"string"}},"FaxId":{"name":"faxId","in":"path","required":true,"description":"UUID of the fax","schema":{"type":"string","format":"uuid"}}},"schemas":{"Fax":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string","format":"uuid","nullable":true},"updatedBy":{"type":"string","format":"uuid","nullable":true},"createdByName":{"type":"string"},"updatedByName":{"type":"string"},"faxId":{"type":"string","nullable":true,"description":"External fax provider ID"},"externalId":{"type":"string","format":"uuid","nullable":true},"direction":{"type":"string","enum":["IN","OUT"]},"fromNumber":{"type":"string","description":"E.164 format"},"sender":{"$ref":"#/components/schemas/FaxParty"},"toNumber":{"type":"string","nullable":true,"description":"E.164 format"},"receiver":{"$ref":"#/components/schemas/FaxParty","nullable":true},"subject":{"type":"string","nullable":true},"status":{"type":"string","enum":["DRAFT","PROCESSING","DELIVERED","FAILED"]},"originalStatus":{"type":"string","nullable":true,"description":"Raw status string from the fax provider"},"statusMessage":{"type":"string","nullable":true},"document":{"$ref":"#/components/schemas/FaxDocument"},"patient":{"$ref":"#/components/schemas/FaxPatient"},"receivedAt":{"type":"string","format":"date-time","nullable":true},"highQuality":{"type":"boolean"},"files":{"type":"array","items":{"$ref":"#/components/schemas/FaxFile"}},"sentBy":{"type":"string","format":"uuid","nullable":true},"sentByName":{"type":"string","nullable":true},"reviewed":{"type":"boolean"}}},"FaxParty":{"type":"object","description":"Sender or receiver of a fax.","required":["type","faxNumber"],"properties":{"type":{"type":"string","enum":["FAX_NUMBER","SYSTEM_FAX_NUMBER"],"description":"`FAX_NUMBER` for external parties, `SYSTEM_FAX_NUMBER` for Welkin system numbers"},"faxNumber":{"type":"string","description":"E.164 format"}}},"FaxDocument":{"type":"object","nullable":true,"description":"Document record linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"title":{"type":"string"}}},"FaxPatient":{"type":"object","nullable":true,"description":"Patient linked to this fax, if assigned.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"FaxFile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"originalName":{"type":"string"},"size":{"type":"integer","description":"File size in bytes"},"contentType":{"type":"string"},"storageKey":{"type":"string"}}},"AssignFaxRequest":{"type":"object","required":["patientId"],"properties":{"patientId":{"type":"string","format":"uuid"},"documentType":{"type":"string","description":"Required for incoming faxes — the document type to file the fax under."}}}},"responses":{"BadRequest":{"description":"Bad request — the request could not be understood or was missing required parameters."},"Unauthorized":{"description":"Unauthorized — the Bearer token is missing, expired, or invalid."},"Forbidden":{"description":"Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin."},"NotFound":{"description":"Not found — the requested resource does not exist."},"TooManyRequests":{"description":"Too many requests — rate limit exceeded. Implement exponential backoff."},"InternalError":{"description":"Internal server error."}}},"paths":{"/{tenantName}/{instanceName}/faxes/{faxId}/assign":{"post":{"summary":"Assign Fax","tags":["Fax"],"operationId":"Assign_Fax","parameters":[{"$ref":"#/components/parameters/TenantName"},{"$ref":"#/components/parameters/InstanceName"},{"$ref":"#/components/parameters/FaxId"}],"responses":{"200":{"description":"Updated fax with patient assigned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fax"}}}},"201":{"description":"Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalError"}},"description":"Request to assign a patient to the fax.\n\nFor an incoming fax, the request body is required to include the patient ID and the document type in which the fax file will be saved.\n\nFor an outgoing fax, only the patient ID is enough.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignFaxRequest"}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.welkinhealth.com/api-reference/fax.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.