Communication

An occurrence of information being transmitted; e.g. a message that was sent to a responsible provider

https://hl7.org/fhir/R4/communication.html

The Communication resource maps to messages in Canvas between a patient and practitioner. Click here to learn more.

Additional HTML formatting
With the release of Advanced Letter Templates, Messages are now saved in the database in HTML format. Customers using the Communication endpoint for their own patient applications will need to take this into account either by embedding the html directly using a library like Interweave or extracting the text. Messages sent before this update (10/26/2022 @ 17:00 PST) will remain in plain text format.

Related guides:

Endpoints

post
/Communication
 get
/Communication/{id}
 get
/Communication
post
/Communication

Communication create

Messages created through this endpoint will be added to the patient’s timeline and in the patient app based on the ingestion date into Canvas.

Attributes

resourceType
string

The FHIR Resource name.

status
string required

The status of the transmission.

While status is a required attribute, all communication messages will be created with a completed status regardless of what is supplied in the payload.

Value Options Supported:
  • completed
  • in-progress
  • preparation
  • unknown
sent
datetime

When sent

ISO 8601 format

If not supplied on creation, it will default to the current timestamp.

received
datetime

When received

ISO 8601 format

If no received datetime is supplied when the recipient of the message is a Practitioner, the message will appear on the subject’s timeline as unread, indicated by a blue circle on the message icon. The practitioner will have the ability to mark the communication message as read in the Canvas UI which will update this attribute.

recipient
array[json] required

Message recipient.

Supported reference types are a single Patient or Practitioner.

Between the sender and recipient, one must be a practitioner while the other must be a patient.

Click to view child attributes
reference
string required

The reference string of the sender in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787" or "Practitioner/ed1e304acdb847148338c6b0596d93fd".

type
string

Type the reference refers to (e.g. “Patient” or “Practitioner”).

sender
json required

Message sender.

Supported reference types are a single Patient or Practitioner.

Between the sender and recipient, one must be a practitioner while the other must be a patient.

Click to view child attributes
reference
string required

The reference string of the sender in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787" or "Practitioner/ed1e304acdb847148338c6b0596d93fd".

type
string

Type the reference refers to (e.g. “Patient” or “Practitioner”).

payload
array[json] required

Message payload.

Messages are now saved in the Canvas database in HTML format. Customers using the Communication endpoint for their own patient applications will need to take this into account either by embedding the html directly using a library like Interweave or extracting the text. Messages sent before 10/26/2022 @ 17:00 PST will remain in plain text format.

Click to view child attributes
contentString
string required

Message part content.

Responses

201 Created
The server has successfully processed the request; the new resource has been created and is now ready for interaction.

Canvas returns the created resource's id as a UUID within the location header and a null response body.

Errors

400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
405 Method Not Allowed
The request performs an operation that is either not supported or allowed.
422 Unprocessable Entity
The request cannot be processed due to semantic issues or conflicts with the database state.
get
/Communication/{id}

Communication read

Read a Communication resource.

Path Parameters

id required
string
The unique identifier for the Communication

Response Payload Attributes

resourceType
string

The FHIR Resource name.

id
string

The identifier of the communication.

status
string

The status of the transmission.

A communication message in Canvas that was sent, received, delivered, or relayed will all appear in FHIR as completed. For draft messages in Canvas, they will appear in FHIR as preparation. While a FHIR status of in-progress are Canvas messages that are scheduled to be delivered at a later time.

Value Options Supported:
  • completed
  • in-progress
  • preparation
  • unknown
subject
json

Focus of the message. Always a Patient reference.

Click to view child attributes
reference
string

The reference string of the subject in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787".

type
string

Type the reference refers to (e.g. “Patient”).

sent
datetime

When sent

ISO 8601 format

received
datetime

When received

ISO 8601 format

Messages sent via Canvas UI to a patient will not have a received timestamp.

If the received timestamp is not added via API to messages sent to practitioners, it can still be updated if the practitioner manually marks the message as read in the UI.

recipient
array[json]

Message recipient.

Supported reference types are a single Patient or Practitioner.

Click to view child attributes
reference
string

The reference string of the sender in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787" or "Practitioner/ed1e304acdb847148338c6b0596d93fd".

type
string

Type the reference refers to (e.g. “Patient” or “Practitioner”).

sender
json

Message sender.

Supported reference types are a single Patient or Practitioner.

Click to view child attributes
reference
string

The reference string of the sender in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787" or "Practitioner/ed1e304acdb847148338c6b0596d93fd".

type
string

Type the reference refers to (e.g. “Patient” or “Practitioner”).

payload
array[json]

Message payload.

Messages are now saved in the Canvas database in HTML format. Customers using the Communication endpoint for their own patient applications will need to take this into account either by embedding the html directly using a library like Interweave or extracting the text. Messages sent before 10/26/2022 @ 17:00 PST will remain in plain text format.

Click to view child attributes
contentString
string

Message part content.

Responses

200 OK
Request was successful.

Errors

401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
404 Not Found
The requested resource was not found.
get
/Communication

Communication search

Communication search will only return messages between a practitioner and patient, not between two practitioners.

Query Parameters

_id
string

The unique Canvas identifier of the Communication.

patient
string

The patient reference that is the subject of the communication in the format Patient/a39cafb9d1b445be95a2e2548e12a787.

recipient
string

Message recipient in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787" or "Practitioner/ed1e304acdb847148338c6b0596d93fd".

sender
string

Message sender in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787" or "Practitioner/ed1e304acdb847148338c6b0596d93fd".

Response Payload Attributes

resourceType
string

The FHIR Resource name.

type
string

This element and value designate that the bundle is a search response. Search result bundles will always have the Bundle.type of searchset .

total
integer

The number of resources that match the search parameter.

link
array[json]

Attributes relevant to pagination, see our Pagination page for more detail.

Click to view child attributes
relation
enum [self|first|next|last]

The relation of the page search

url

The search url for the specific relation

entry
array[json]

The results bundle that lists out each object returned in the search

Click to view child attributes
resource
json

The attributes specific to the resource type, see the Attributes section below

Attributes

resourceType
string

The FHIR Resource name.

id
string

The identifier of the communication.

status
string

The status of the transmission.

A communication message in Canvas that was sent, received, delivered, or relayed will all appear in FHIR as completed. For draft messages in Canvas, they will appear in FHIR as preparation. While a FHIR status of in-progress are Canvas messages that are scheduled to be delivered at a later time.

Value Options Supported:
  • completed
  • in-progress
  • preparation
  • unknown
subject
json

Focus of the message. Always a Patient reference.

Click to view child attributes
reference
string

The reference string of the subject in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787".

type
string

Type the reference refers to (e.g. “Patient”).

sent
datetime

When sent

ISO 8601 format

received
datetime

When received

ISO 8601 format

Messages sent via Canvas UI to a patient will not have a received timestamp.

If the received timestamp is not added via API to messages sent to practitioners, it can still be updated if the practitioner manually marks the message as read in the UI.

recipient
array[json]

Message recipient.

Supported reference types are a single Patient or Practitioner.

Click to view child attributes
reference
string

The reference string of the sender in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787" or "Practitioner/ed1e304acdb847148338c6b0596d93fd".

type
string

Type the reference refers to (e.g. “Patient” or “Practitioner”).

sender
json

Message sender.

Supported reference types are a single Patient or Practitioner.

Click to view child attributes
reference
string

The reference string of the sender in the format of "Patient/a39cafb9d1b445be95a2e2548e12a787" or "Practitioner/ed1e304acdb847148338c6b0596d93fd".

type
string

Type the reference refers to (e.g. “Patient” or “Practitioner”).

payload
array[json]

Message payload.

Messages are now saved in the Canvas database in HTML format. Customers using the Communication endpoint for their own patient applications will need to take this into account either by embedding the html directly using a library like Interweave or extracting the text. Messages sent before 10/26/2022 @ 17:00 PST will remain in plain text format.

Click to view child attributes
contentString
string

Message part content.

Responses

200 OK
Request was successful.

Errors

400 Bad Request
The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401 Unauthorized
The request requires user authentication.
403 Forbidden
The request requires user authorization.
  • curl --request POST \
     --url 'https://fumage-example.canvasmedical.com/Communication' \
     --header 'Authorization: Bearer <token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "resourceType": "Communication",
  "status": "unknown",
  "sent": "2022-04-29T13:30:00.000Z",
  "received": "2022-04-29T13:30:00.000Z",
  "recipient": [
    {
      "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd"
    }
  ],
  "sender": {
    "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14"
  },
  "payload": [
    {
      "contentString": "Upcoming appointment"
    }
  ]
}'

  • import requests

url = "https://fumage-example.canvasmedical.com/Communication"

payload = {
    "resourceType": "Communication",
    "sent": "2022-04-29T13:30:00.000Z",
    "received": "2022-04-29T13:30:00.000Z",
    "recipient": [{ "reference": "Patient/b3084f7e884e4af2b7e23b1dca494abd" }],
    "sender": { "reference": "Practitioner/5eede137ecfe4124b8b773040e33be14" },
    "payload": [{ "contentString": "Upcoming appointment" }]
}
headers = {
    "accept": "application/json",
    "Authorization": "Bearer <token>",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

  • null

  • {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Bad request"
      }
    }
  ]
}

  • {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "unknown",
      "details": {
        "text": "Authentication failed"
      }
    }
  ]
}

  • {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "forbidden",
      "details": {
        "text": "Authorization failed"
      }
    }
  ]
}

  • {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-supported",
      "details": {
        "text": "Operation is not supported"
      }
    }
  ]
}

  • {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "business-rule",
      "details": {
        "text": "Unprocessable entity"
      }
    }
  ]
}

  • curl --request GET \
     --url 'https://fumage-example.canvasmedical.com/Communication?recipient=Patient/b3084f7e884e4af2b7e23b1dca494abd' \
     --header 'Authorization: Bearer <token>' \
     --header 'accept: application/json'

  • import requests

url = "https://fumage-example.canvasmedical.com/Communication?recipient=Patient/b3084f7e884e4af2b7e23b1dca494abd"

headers = {
    "accept": "application/json",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

  • {
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "link": [
    {
      "relation": "self",
      "url": "/Communication?_id=7433b4b2-0d18-45ca-bb12-71105c80386b&_count=10&_offset=0"
    },
    {
      "relation": "first",
      "url": "/Communication?_id=7433b4b2-0d18-45ca-bb12-71105c80386b&_count=10&_offset=0"
    },
    {
      "relation": "last",
      "url": "/Communication?_id=7433b4b2-0d18-45ca-bb12-71105c80386b&_count=10&_offset=0"
    }
  ],
  "entry": [
    {
      "resource": {
        "resourceType": "Communication",
        "id": "7433b4b2-0d18-45ca-bb12-71105c80386b",
        "status": "unknown",
        "sent": "2021-03-21T10:46:17+00:00",
        "received": "2022-03-14T12:03:58.958000+00:00",
        "recipient": [
          {
            "reference": "Patient/4c21512185184e579b09bfac16dfdd2f",
            "type": "Patient"
          }
        ],
        "sender": {
            "reference": "Practitioner/4150cd20de8a470aa570a852859ac87e",
            "type": "Practitioner"
        },
        "payload": [
          {
            "contentString": "Similique amet at est necessitatibus repellendus eius."
          }
        ]
      }
    }
  ]
}

  • {
  "resourceType": "OperationOutcome",
  "id": "101",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Bad request"
      }
    }
  ]
}

  • {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "unknown",
      "details": {
        "text": "Authentication failed"
      }
    }
  ]
}

  • {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "forbidden",
      "details": {
        "text": "Authorization failed"
      }
    }
  ]
}

  • curl --request GET \
     --url 'https://fumage-example.canvasmedical.com/Communication/<id>' \
     --header 'Authorization: Bearer <token>' \
     --header 'accept: application/json'

  • import requests

url = "https://fumage-example.canvasmedical.com/Communication/<id>"

headers = {
    "accept": "application/json",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

  • {
    "resourceType": "Communication",
    "id": "17b7d61e-4b0e-4940-bd37-b64f5c2ae29d",
    "status": "unknown",
    "sent": "2023-10-23T21:19:22.865089+00:00",
    "recipient": [
        {
            "reference": "Practitioner/3640cd20de8a470aa570a852859ac87e",
            "type": "Practitioner"
        }
    ],
    "sender": {
        "reference": "Patient/43f1418bae9c41919203e0006761067c",
        "type": "Patient"
    },
    "payload": [
        {
            "contentString": "What's up doc?"
        }
    ]
}


  • {
  "resourceType": "OperationOutcome",
  "id": "101",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Bad request"
      }
    }
  ]
}

  • {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "unknown",
      "details": {
        "text": "Authentication failed"
      }
    }
  ]
}

  • {
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "forbidden",
      "details": {
        "text": "Authorization failed"
      }
    }
  ]
}