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. 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 based on the created date.

If the sender of the message is a Practitioner, the message will be displayed as a draft in the timeline, drafter by Canvas Bot. There is no way to mark it as sent via the API today.

If the sender of the message is a patient, the message will show in the recipient’s message inbox for review, as well as on the timeline.

Attributes

id
string

The identifier of the communication

status
string required

Supported codes for create interactions are unknown.

subject
json

Focus of the message. Always a Patient reference

sent
datetime

When sent

ISO 8601 format

received
datetime

When received

ISO 8601 format

recipient
array[json] required

Message recipient

Supported reference types for create interactions: a single Patient or Practitioner

sender
json required

Message sender

Supported reference types for create interactions: Patient, Practitioner

payload
array[json] required

Message payload

Supported payload content types: contentString

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

id
string

The identifier of the communication

status
string

The status of the transmission.

subject
json

Focus of the message. Always a Patient reference

sent
datetime

When sent

ISO 8601 format

received
datetime

When received

ISO 8601 format

recipient
array[json]

Message recipient

Supported reference types for create interactions: a single Patient or Practitioner

sender
json

Message sender

Supported reference types for create interactions: Patient, Practitioner

payload
array[json]

Message payload

Supported payload content types: contentString

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

Focus of message

Supported: Patient

recipient
string

Message recipient

Supported: Patient, Practitioner

sender
string

Message sender

Supported: Patient, Practitioner

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

id
string

The identifier of the communication

status
string

The status of the transmission.

subject
json

Focus of the message. Always a Patient reference

sent
datetime

When sent

ISO 8601 format

received
datetime

When received

ISO 8601 format

recipient
array[json]

Message recipient

Supported reference types for create interactions: a single Patient or Practitioner

sender
json

Message sender

Supported reference types for create interactions: Patient, Practitioner

payload
array[json]

Message payload

Supported payload content types: contentString

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%2Fb3084f7e884e4af2b7e23b1dca494abd' \
     --header 'Authorization: Bearer <token>' \
     --header 'accept: application/json'

  • import requests

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

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"
      }
    }
  ]
}