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

Attributes

id
string

The identifier of the communication

status
string required

The status of the transmission

Supported codes for create interactions are: unknown

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

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

The status of the transmission

Supported codes for create interactions are: unknown

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.

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

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

recipient
array[json]

Message recipient

Supported: Patient, Practitioner

sender
string

Message sender

Supported: Patient, Practitioner

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