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

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.

Setting up the type of consents allowed in your instance must be completed before using this endpoint. See the related guide above for details.

Attributes

id
string

The identifier of the Consent

status
string required

Indicates the current state of this consent

Supported codes for create interactions are: active, inactive, and rejected

scope
json required

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

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

category
array[json] required

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

patient
json required

Who the consent applies to

dateTime
datetime required

When this Consent was issued / created / indexed

For create interactions, this value will be ignored.

For read/search interactions, this value will be the Consent’s create datetime.

sourceAttachment
json required

The source on which this consent statement is based.

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

For read/search interactions, Canvas returns the sourceAttachment.url.

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.

provision
json

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.

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

id
string

The identifier of the Consent

status
string

Indicates the current state of this consent

Supported codes for create interactions are: active, inactive, and rejected

scope
json

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

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

category
array[json]

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

patient
json

Who the consent applies to

dateTime
datetime

When this Consent was issued / created / indexed

For create interactions, this value will be ignored.

For read/search interactions, this value will be the Consent’s create datetime.

sourceAttachment
json

The source on which this consent statement is based.

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

For read/search interactions, Canvas returns the sourceAttachment.url.

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.

provision
json

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.

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

period
date

Timeframe for this rule

Expects date strings formatted like YYYY-MM-DD, prefaced with one of eq, lt, le, gt, ge.

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 Consent

status
string

Indicates the current state of this consent

Supported codes for create interactions are: active, inactive, and rejected

scope
json

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

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

category
array[json]

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

patient
json

Who the consent applies to

dateTime
datetime

When this Consent was issued / created / indexed

For create interactions, this value will be ignored.

For read/search interactions, this value will be the Consent’s create datetime.

sourceAttachment
json

The source on which this consent statement is based.

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

For read/search interactions, Canvas returns the sourceAttachment.url.

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.

provision
json

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.

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.