Consent

A record of a healthcare consumer’s choices, which permits or denies identified recipient(s) or recipient role(s) to perform one or more actions within a given policy context, for specific purposes and periods of time.

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

For more information on consents in canvas, see this article.

Related guides:

Endpoints

post
/Consent
 get
/Consent/{id}
 get
/Consent
post
/Consent

Consent create

Before creating a consent via the API, Patient Consent Codings must be configured in Canvas.

Updating existing patient consent objects

A patient consent is uniquely distinguished by its patient and consent coding

This Create endpoint also acts as an Update endpoint. If the patient already has an existing patient consent with the same consent coding, the endpoint updates that consent in place and the id returned in the response will not be changed.

Attributes

resourceType
string

The FHIR Resource name.

status
string required

Indicates the current state of this consent.

Value Options Supported:
  • active
  • rejected
scope
json required

For create interactions, this field is required by FHIR but ignored by Canvas, so {} is an accepted value.

Click to view child attributes
string

Plain text representation of the concept

Value Options Supported:
  • Unknown
category
array[json] required

A system/code or a system/display is required to be able to identify the consent category being created/updated.

Click to view child attributes
coding
array[json] required

Identifies where the definition of the code comes from.

Click to view child attributes
system
string required

The system url of the coding.

code
string

The code of the medication.

display
string

The display name of the coding.

patient
json required

Who the consent applies to

Click to view child attributes
reference
string required

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

type
string

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

sourceAttachment
json required

The source on which this consent statement is based.

The source on which this consent is based.

For create interactions, sourceAttachment.title, sourceAttachment.contentType, and sourceAttachment.data are required.

Click to view child attributes
string required

Label to display in place of the data.

string required

Mime type of the content, with charset etc.

Value Options Supported:
  • application/pdf
string required

Data inline, base64ed.

provision
json required

Constraints to the base Consent.

Canvas uses period.start and period.end to define the start and end dates of the consent.

For create interactions, period.start is required with a YYYY-MM-DD format.

A period.end with a past date will mark the consent as Expired in the UI.

Click to view child attributes
json required

Timeframe for this rule

Click to view child attributes
date required

Starting time with inclusive boundary

date

End time with inclusive boundary, if not ongoing.

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
/Consent/{id}

Consent read

Read a Consent resource

Path Parameters

id required
string
The unique identifier for the Consent

Response Payload Attributes

resourceType
string

The FHIR Resource name.

id
string

The identifier of the Consent.

status
string

Indicates the current state of this consent.

Value Options Supported:
  • active
  • rejected
scope
json

Type of consent being presented (e.g. ADR, Privacy, Treatment, Research).

Click to view child attributes
string

Plain text representation of the concept

Value Options Supported:
  • Unknown
category
array[json]

A classification of the type of consents found in the statement.

The category.coding needs to match a patient consent coding record defined in the Canvas Admin Settings page.

Click to view child attributes
coding
array[json]

Identifies where the definition of the code comes from.

Click to view child attributes
system
string

The system url of the coding.

code
string

The code of the medication.

display
string

The display name of the coding.

patient
json

Who the consent applies to

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”).

dateTime
datetime

When this Consent was issued / created / indexed.

This value will be the Consent’s datetime of ingestion in Canvas.

sourceAttachment
json

The source on which this consent statement is based.

Canvas returns the sourceAttachment.url for the document associated with the consent that has the latest period.start date.

Note: There is a temporary extension that will contain the presigned URL for the Attachment; this will be provided while we migrate to static URLs that will require bearer authentication to retrieve attachment files. Use this extension for backward-compatible URLs until the migration is completed.

Click to view child attributes
url

Uri where the data can be found.

provision
json

Constraints to the base Consent.

Canvas uses period.start and period.end to define the start and end dates of the consent.

Click to view child attributes
json

Timeframe for this rule

Click to view child attributes
date

Starting time with inclusive boundary

date

End time with inclusive boundary, if not ongoing.

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
/Consent

Consent search

Search for Consent resources

Query Parameters

_id
string

The Canvas-issued unique identifier of the Consent.

patient
string

Who the consent applies to in the format Patient/a39cafb9d1b445be95a2e2548e12a787

period
date

Search by the period.start. See Date Filtering for more information.

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 Consent.

status
string

Indicates the current state of this consent.

Value Options Supported:
  • active
  • rejected
scope
json

Type of consent being presented (e.g. ADR, Privacy, Treatment, Research).

Click to view child attributes
string

Plain text representation of the concept

Value Options Supported:
  • Unknown
category
array[json]

A classification of the type of consents found in the statement.

The category.coding needs to match a patient consent coding record defined in the Canvas Admin Settings page.

Click to view child attributes
coding
array[json]

Identifies where the definition of the code comes from.

Click to view child attributes
system
string

The system url of the coding.

code
string

The code of the medication.

display
string

The display name of the coding.

patient
json

Who the consent applies to

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”).

dateTime
datetime

When this Consent was issued / created / indexed.

This value will be the Consent’s datetime of ingestion in Canvas.

sourceAttachment
json

The source on which this consent statement is based.

Canvas returns the sourceAttachment.url for the document associated with the consent that has the latest period.start date.

Note: There is a temporary extension that will contain the presigned URL for the Attachment; this will be provided while we migrate to static URLs that will require bearer authentication to retrieve attachment files. Use this extension for backward-compatible URLs until the migration is completed.

Click to view child attributes
url

Uri where the data can be found.

provision
json

Constraints to the base Consent.

Canvas uses period.start and period.end to define the start and end dates of the consent.

Click to view child attributes
json

Timeframe for this rule

Click to view child attributes
date

Starting time with inclusive boundary

date

End time with inclusive boundary, if not ongoing.

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.