Consents
Overview
This API has been available since 1.7.0
A FusionAuth Consent is a definition of a permission that can be given to a User. At a minimum a consent has a name, and defines the minimum age of self-consent. A consent can then be granted to a User from a family member or optionally a User may self-consent if they meet the minimum age defined by the consent.
The first API allows you to create, delete, update and retrieve a consent. The FusionAuth Consent is the object that defines the consent, the values, minimum ages, etc.
The second API is the User Consent API, this API allows you to grant a User Consent, and update a User Consent. In order to revoke a User Consent you simply need to update the consent status.
Create a Consent
This API is used to create a new Consent.
Request
Request Parameters
consentId
UUIDDefaults to secure random UUIDThe Id to use for the new Consent. If not specified a secure random UUID will be generated.
Request Body
consent.consentEmailTemplateId
UUIDThe Id of the Email Template that is used to send confirmation to the end user. If this value is omitted an email will not be sent to the user.
consent.countryMinimumAgeForSelfConsent
Map<Locale, Integer>This property optionally overrides the value provided in defaultMinimumAgeForSelfConsent if a more specific value is defined. This can be useful when the age of self consent varies by country.
For example, consider the following definition:
{
"de": 17
}
If a user has defined their preferred locale to be Germany (de
), the age of self consent defined for Germany will be used instead of the value defined by defaultMinimumAgeForSelfConsent .
consent.data
ObjectAn object that can hold any information about the Consent that should be persisted.
consent.defaultMinimumAgeForSelfConsent
IntegerrequiredThe default age of self consent used when granting this consent to a user unless a more specific one is provided by the countryMinimumAgeForSelfConsent .
A user that meets the minimum age of self consent may self-consent, this means the recipient may also be the giver.
consent.emailPlus.enabled
BooleanDefaults to falseSet this value to true
to enable the Email Plus workflow.
Email Plus provides and additional opportunity to notify the giver that consent was provided. For example, if consentEmailTemplateId is provided then when the consent is granted an email will be sent to notify the giver that consent was granted to the user. When using Email Plus a follow up email will be sent to the giver at a randomly selected time within the configured minimum and maximum range of hours.
consent.emailPlus.emailTemplateId
UUIDrequiredThe Id of the Email Template that is used to send the reminder notice to the consent giver. This value is required when emailPlus.enabled is set to true
.
consent.emailPlus.maximumTimeToSendEmailInHours
IntegerDefaults to 48The maximum number of hours to wait until sending the reminder notice the consent giver.
consent.emailPlus.minimumTimeToSendEmailInHours
IntegerDefaults to 24The minimum number of hours to wait until sending the reminder notice the consent giver.
consent.multipleValuesAllowed
BooleanDefaults to falseSet this value to true
if more than one value may be used when granting this consent to a User. When this value is false
a maximum of one value may be assigned.
This value is not used when no values have been defined for this consent.
consent.name
StringrequiredThe unique name of the consent.
consent.values
Array<String>One or more values that may be assigned for this consent.
Example Request JSON
{
"consent": {
"consentEmailTemplateId": "61cba163-2d53-4d2d-ad7f-801c27f0c277",
"countryMinimumAgeForSelfConsent": {
"de": 21
},
"defaultMinimumAgeForSelfConsent": 18,
"emailPlus": {
"enabled": true,
"emailTemplateId": "9cd65fca-5aa0-4861-899b-8712d8ec963f",
"maximumTimeToSendEmailInHours": 48,
"minimumTimeToSendEmailInHours": 24
},
"multipleValuesAllowed": false,
"name": "Patient Consent",
"values": [
"Written",
"Verbal"
]
}
}
Response
The response for this API contains the Consent that was created.
Response CodesCode | Description |
---|---|
200 | The request was successful. The response will contain a JSON body. |
400 | The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |
Response Body
consent.consentEmailTemplateId
UUIDThe Id of the Email Template that is used to send confirmation to the end user.
consent.countryMinimumAgeForSelfConsent
Map<Locale, Integer>This property optionally overrides the value provided in defaultMinimumAgeForSelfConsent if a more specific value is defined. This can be useful when the age of self consent varies by country.
For example, consider the following definition:
{
"de": 17
}
If a user has defined their preferred locale to be Germany (de
), the age of self consent defined for Germany will be used instead of the value defined by defaultMinimumAgeForSelfConsent .
consent.data
ObjectAn object that can hold any information about the Consent that should be persisted.
consent.defaultMinimumAgeForSelfConsent
IntegerThe default age of self consent used when granting this consent to a user unless a more specific one is provided by the countryMinimumAgeForSelfConsent .
A user that meets the minimum age of self consent may self-consent, this means the recipient may also be the giver.
consent.emailPlus.enabled
BooleanWhen this value is true
the Email Plus workflow is enabled.
Email Plus provides and additional opportunity to notify the giver that consent was provided. For example, if consentEmailTemplateId is provided then when the consent is granted an email will be sent to notify the giver that consent was granted to the user. When using Email Plus a follow up email will be sent to the giver at a randomly selected time within the configured minimum and maximum range of hours.
consent.emailPlus.emailTemplateId
UUIDThe Id of the Email Template that is used to send the reminder notice to the consent giver.
consent.emailPlus.maximumTimeToSendEmailInHours
IntegerThe maximum number of hours to wait until sending the reminder notice the consent giver.
consent.emailPlus.minimumTimeToSendEmailInHours
IntegerThe minimum number of hours to wait until sending the reminder notice the consent giver.
consent.id
UUIDThe unique Id of the consent.
consent.insertInstant
LongThe instant that the Consent was added to the FusionAuth database.
consent.lastUpdateInstant
LongThe instant that the Consent was updated in the FusionAuth database.
consent.multipleValuesAllowed
BooleanWhen this value is true
more than one value may be used when granting this consent to a User.
This value is not used when no values have been defined for this consent.
consent.name
StringThe unique name of the consent.
consent.values
Array<String>One or more values that may be assigned for this consent.
Example Response JSON
{
"consent": {
"consentEmailTemplateId": "61cba163-2d53-4d2d-ad7f-801c27f0c277",
"countryMinimumAgeForSelfConsent": {
"de": 21
},
"defaultMinimumAgeForSelfConsent": 18,
"emailPlus": {
"enabled": true,
"emailTemplateId": "9cd65fca-5aa0-4861-899b-8712d8ec963f",
"maximumTimeToSendEmailInHours": 48,
"minimumTimeToSendEmailInHours": 24
},
"id": "d512b9b8-876f-4b5e-81f0-3e180b6ea485",
"insertInstant": 1595361142909,
"lastUpdateInstant": 1595361143101,
"multipleValuesAllowed": false,
"name": "Patient Consent",
"values": [
"Written",
"Verbal"
]
}
}
Retrieve a Consent
This API is used to retrieve a single Consent by unique Id or all of the configured Consents.
Request
Request Parameters
consentId
UUIDrequiredThe unique Id of the Consent to retrieve.
Response
The response for this API contains either a single Consent or all of the Consents. When you call this API with an Id the response will contain a single Consent. When you call this API without an Id the response will contain all of the Consents. Both response types are defined below along with an example JSON response.
Response CodesCode | Description |
---|---|
200 | The request was successful. The response will contain a JSON body. |
400 | The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
404 | The object you requested doesn't exist. The response will be empty. |
500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |
Response Body
consent.consentEmailTemplateId
UUIDThe Id of the Email Template that is used to send confirmation to the end user.
consent.countryMinimumAgeForSelfConsent
Map<Locale, Integer>This property optionally overrides the value provided in defaultMinimumAgeForSelfConsent if a more specific value is defined. This can be useful when the age of self consent varies by country.
For example, consider the following definition:
{
"de": 17
}
If a user has defined their preferred locale to be Germany (de
), the age of self consent defined for Germany will be used instead of the value defined by defaultMinimumAgeForSelfConsent .
consent.data
ObjectAn object that can hold any information about the Consent that should be persisted.
consent.defaultMinimumAgeForSelfConsent
IntegerThe default age of self consent used when granting this consent to a user unless a more specific one is provided by the countryMinimumAgeForSelfConsent .
A user that meets the minimum age of self consent may self-consent, this means the recipient may also be the giver.
consent.emailPlus.enabled
BooleanWhen this value is true
the Email Plus workflow is enabled.
Email Plus provides and additional opportunity to notify the giver that consent was provided. For example, if consentEmailTemplateId is provided then when the consent is granted an email will be sent to notify the giver that consent was granted to the user. When using Email Plus a follow up email will be sent to the giver at a randomly selected time within the configured minimum and maximum range of hours.
consent.emailPlus.emailTemplateId
UUIDThe Id of the Email Template that is used to send the reminder notice to the consent giver.
consent.emailPlus.maximumTimeToSendEmailInHours
IntegerThe maximum number of hours to wait until sending the reminder notice the consent giver.
consent.emailPlus.minimumTimeToSendEmailInHours
IntegerThe minimum number of hours to wait until sending the reminder notice the consent giver.
consent.id
UUIDThe unique Id of the consent.
consent.insertInstant
LongThe instant that the Consent was added to the FusionAuth database.
consent.lastUpdateInstant
LongThe instant that the Consent was updated in the FusionAuth database.
consent.multipleValuesAllowed
BooleanWhen this value is true
more than one value may be used when granting this consent to a User.
This value is not used when no values have been defined for this consent.
consent.name
StringThe unique name of the consent.
consent.values
Array<String>One or more values that may be assigned for this consent.
Example Response JSON
{
"consent": {
"consentEmailTemplateId": "61cba163-2d53-4d2d-ad7f-801c27f0c277",
"countryMinimumAgeForSelfConsent": {
"de": 21
},
"defaultMinimumAgeForSelfConsent": 18,
"emailPlus": {
"enabled": true,
"emailTemplateId": "9cd65fca-5aa0-4861-899b-8712d8ec963f",
"maximumTimeToSendEmailInHours": 48,
"minimumTimeToSendEmailInHours": 24
},
"id": "d512b9b8-876f-4b5e-81f0-3e180b6ea485",
"insertInstant": 1595361142909,
"lastUpdateInstant": 1595361143101,
"multipleValuesAllowed": false,
"name": "Patient Consent",
"values": [
"Written",
"Verbal"
]
}
}
Response Body
consents
ArrayThe list of Consent objects.
consents[x].consentEmailTemplateId
UUIDThe Id of the Email Template that is used to send confirmation to the end user.
consents[x].countryMinimumAgeForSelfConsent
Map<Locale, Integer>This property optionally overrides the value provided in defaultMinimumAgeForSelfConsent if a more specific value is defined. This can be useful when the age of self consent varies by country.
For example, consider the following definition:
{
"de": 17
}
If a user has defined their preferred locale to be Germany (de
), the age of self consent defined for Germany will be used instead of the value defined by defaultMinimumAgeForSelfConsent .
consents[x].defaultMinimumAgeForSelfConsent
IntegerThe default age of self consent used when granting this consent to a user unless a more specific one is provided by the countryMinimumAgeForSelfConsent .
A user that meets the minimum age of self consent may self-consent, this means the recipient may also be the giver.
consents[x].emailPlus.enabled
BooleanWhen this value is true
the Email Plus workflow is enabled.
Email Plus provides and additional opportunity to notify the giver that consent was provided. For example, if consentEmailTemplateId is provided then when the consent is granted an email will be sent to notify the giver that consent was granted to the user. When using Email Plus a follow up email will be sent to the giver at a randomly selected time within the configured minimum and maximum range of hours.
consents[x].emailPlus.emailTemplateId
UUIDThe Id of the Email Template that is used to send the reminder notice to the consent giver.
consents[x].emailPlus.maximumTimeToSendEmailInHours
IntegerThe maximum number of hours to wait until sending the reminder notice the consent giver.
consents[x].emailPlus.minimumTimeToSendEmailInHours
IntegerThe minimum number of hours to wait until sending the reminder notice the consent giver.
consents[x].id
UUIDThe unique Id of the consent.
consent[x].insertInstant
LongThe instant that the Consent was added to the FusionAuth database.
consent[x].lastUpdateInstant
LongThe instant that the Consent was updated in the FusionAuth database.
consents[x].multipleValuesAllowed
BooleanWhen this value is true
more than one value may be used when granting this consent to a User.
This value is not used when no values have been defined for this consent.
consents[x].name
StringThe unique name of the consent.
consents[x].values
Array<String>One or more values that may be assigned for this consent.
Example Response JSON
{
"consents": [
{
"consentEmailTemplateId": "61cba163-2d53-4d2d-ad7f-801c27f0c277",
"countryMinimumAgeForSelfConsent": {
"de": 21
},
"defaultMinimumAgeForSelfConsent": 18,
"emailPlus": {
"enabled": true,
"emailTemplateId": "9cd65fca-5aa0-4861-899b-8712d8ec963f",
"maximumTimeToSendEmailInHours": 48,
"minimumTimeToSendEmailInHours": 24
},
"id": "d512b9b8-876f-4b5e-81f0-3e180b6ea485",
"insertInstant": 1595361142909,
"lastUpdateInstant": 1595361143101,
"multipleValuesAllowed": false,
"name": "Patient Consent",
"values": [
"Written",
"Verbal"
]
}
]
}
Update a Consent
This API is used to update an existing Consent.
You must specify all of the properties of the Consent when calling this API with the PUT
HTTP method. When used with PUT
, this API doesn’t merge the existing Consent and your new data. It replaces the existing Consent with your new data.
Utilize the PATCH
HTTP method to send specific changes to merge into an existing Consent.
Request
When using the PATCH method, you can either use the same request body documentation that is provided for the PUT request for backward compatibility. Or you may use either JSON Patch/RFC 6902] or JSON Merge Patch/RFC 7396. See the PATCH documentation for more information.
When using the PATCH method with a Content-Type
of application/json
the provided request parameters will be merged into the existing object, this means all parameters are optional when using the PATCH method and you only provide the values you want changed. A null
value can be used to remove a value. Patching an Array
will result in all values from the new list being appended to the existing list, this is a known limitation to the current implementation of PATCH.
Request Parameters
consentId
UUIDrequiredThe Id to use for the Consent to update.
Request Body
consent.consentEmailTemplateId
UUIDThe Id of the Email Template that is used to send confirmation to the end user. If this value is omitted an email will not be sent to the user.
consent.countryMinimumAgeForSelfConsent
Map<Locale, Integer>This property optionally overrides the value provided in defaultMinimumAgeForSelfConsent if a more specific value is defined. This can be useful when the age of self consent varies by country.
For example, consider the following definition:
{
"de": 17
}
If a user has defined their preferred locale to be Germany (de
), the age of self consent defined for Germany will be used instead of the value defined by defaultMinimumAgeForSelfConsent .
consent.data
ObjectAn object that can hold any information about the Consent that should be persisted.
consent.defaultMinimumAgeForSelfConsent
IntegerrequiredThe default age of self consent used when granting this consent to a user unless a more specific one is provided by the countryMinimumAgeForSelfConsent .
A user that meets the minimum age of self consent may self-consent, this means the recipient may also be the giver.
consent.emailPlus.enabled
BooleanDefaults to falseSet this value to true
to enable the Email Plus workflow.
Email Plus provides and additional opportunity to notify the giver that consent was provided. For example, if consentEmailTemplateId is provided then when the consent is granted an email will be sent to notify the giver that consent was granted to the user. When using Email Plus a follow up email will be sent to the giver at a randomly selected time within the configured minimum and maximum range of hours.
consent.emailPlus.emailTemplateId
UUIDrequiredThe Id of the Email Template that is used to send the reminder notice to the consent giver. This value is required when emailPlus.enabled is set to true
.
consent.emailPlus.maximumTimeToSendEmailInHours
IntegerDefaults to 48The maximum number of hours to wait until sending the reminder notice the consent giver.
consent.emailPlus.minimumTimeToSendEmailInHours
IntegerDefaults to 24The minimum number of hours to wait until sending the reminder notice the consent giver.
consent.multipleValuesAllowed
BooleanDefaults to falseSet this value to true
if more than one value may be used when granting this consent to a User. When this value is false
a maximum of one value may be assigned.
This value is not used when no values have been defined for this consent.
consent.name
StringrequiredThe unique name of the consent.
consent.values
Array<String>One or more values that may be assigned for this consent.
Example Request JSON
{
"consent": {
"consentEmailTemplateId": "61cba163-2d53-4d2d-ad7f-801c27f0c277",
"countryMinimumAgeForSelfConsent": {
"de": 21
},
"defaultMinimumAgeForSelfConsent": 18,
"emailPlus": {
"enabled": true,
"emailTemplateId": "9cd65fca-5aa0-4861-899b-8712d8ec963f",
"maximumTimeToSendEmailInHours": 48,
"minimumTimeToSendEmailInHours": 24
},
"multipleValuesAllowed": false,
"name": "Patient Consent",
"values": [
"Written",
"Verbal"
]
}
}
Response
The response for this API contains the Consent that was updated.
Response CodesCode | Description |
---|---|
200 | The request was successful. The response will contain a JSON body. |
400 | The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
404 | The object you are trying to update doesn't exist. The response will be empty. |
500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |
Response Body
consent.consentEmailTemplateId
UUIDThe Id of the Email Template that is used to send confirmation to the end user.
consent.countryMinimumAgeForSelfConsent
Map<Locale, Integer>This property optionally overrides the value provided in defaultMinimumAgeForSelfConsent if a more specific value is defined. This can be useful when the age of self consent varies by country.
For example, consider the following definition:
{
"de": 17
}
If a user has defined their preferred locale to be Germany (de
), the age of self consent defined for Germany will be used instead of the value defined by defaultMinimumAgeForSelfConsent .
consent.data
ObjectAn object that can hold any information about the Consent that should be persisted.
consent.defaultMinimumAgeForSelfConsent
IntegerThe default age of self consent used when granting this consent to a user unless a more specific one is provided by the countryMinimumAgeForSelfConsent .
A user that meets the minimum age of self consent may self-consent, this means the recipient may also be the giver.
consent.emailPlus.enabled
BooleanWhen this value is true
the Email Plus workflow is enabled.
Email Plus provides and additional opportunity to notify the giver that consent was provided. For example, if consentEmailTemplateId is provided then when the consent is granted an email will be sent to notify the giver that consent was granted to the user. When using Email Plus a follow up email will be sent to the giver at a randomly selected time within the configured minimum and maximum range of hours.
consent.emailPlus.emailTemplateId
UUIDThe Id of the Email Template that is used to send the reminder notice to the consent giver.
consent.emailPlus.maximumTimeToSendEmailInHours
IntegerThe maximum number of hours to wait until sending the reminder notice the consent giver.
consent.emailPlus.minimumTimeToSendEmailInHours
IntegerThe minimum number of hours to wait until sending the reminder notice the consent giver.
consent.id
UUIDThe unique Id of the consent.
consent.insertInstant
LongThe instant that the Consent was added to the FusionAuth database.
consent.lastUpdateInstant
LongThe instant that the Consent was updated in the FusionAuth database.
consent.multipleValuesAllowed
BooleanWhen this value is true
more than one value may be used when granting this consent to a User.
This value is not used when no values have been defined for this consent.
consent.name
StringThe unique name of the consent.
consent.values
Array<String>One or more values that may be assigned for this consent.
Example Response JSON
{
"consent": {
"consentEmailTemplateId": "61cba163-2d53-4d2d-ad7f-801c27f0c277",
"countryMinimumAgeForSelfConsent": {
"de": 21
},
"defaultMinimumAgeForSelfConsent": 18,
"emailPlus": {
"enabled": true,
"emailTemplateId": "9cd65fca-5aa0-4861-899b-8712d8ec963f",
"maximumTimeToSendEmailInHours": 48,
"minimumTimeToSendEmailInHours": 24
},
"id": "d512b9b8-876f-4b5e-81f0-3e180b6ea485",
"insertInstant": 1595361142909,
"lastUpdateInstant": 1595361143101,
"multipleValuesAllowed": false,
"name": "Patient Consent",
"values": [
"Written",
"Verbal"
]
}
}
Delete a Consent
This API is used to permanently delete a Consent. Deleting a Consent will also permanently delete all granted User Consent. This operation cannot be reversed and it may affect users across multiple tenants.
Request
Request Parameters
consentId
UUIDrequiredThe unique Id of the Consent to delete.
Response
This API does not return a JSON response body.
Response CodesCode | Description |
---|---|
200 | The request was successful. |
400 | The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
404 | The object you requested doesn't exist. The response will be empty. |
500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |
Search for Consents
This API has been available since 1.45.0
This API is used to search for Consents and may be called using the GET
or POST
HTTP methods. Examples of each are provided below. The POST
method is provided to allow for a richer request object without worrying about exceeding the maximum length of a URL. Calling this API with either the GET
or POST
HTTP method will provide the same search results given the same query parameters.
Request
Request Parameters
name
StringThe case-insensitive string to search for in the Consent name. This can contain wildcards using the asterisk character (*
). If no wildcards are present, the search criteria will be interpreted as *value*
.
numberOfResults
IntegerDefaults to 25The number of results to return from the search.
orderBy
StringDefaults to name ASCThe field to order the search results as well as an order direction.
The possible values are:
id
- the unique Id of the ConsentinsertInstant
- the instant when the Consent was createdname
- the Consent name
The order direction is optional. Possible values of the order direction are ASC
or DESC
. If omitted, the default sort order is ASC
.
For example, to order the results by the insert instant in a descending order, use insertInstant DESC
.
startRow
IntegerDefaults to 0The offset into the total results. In order to paginate the results, increment this value by the numberOfResults for subsequent requests.
For example, if the total search results are greater than the page size designated by numberOfResults , set this value to 25
to retrieve results 26-50
, assuming the default page size.
When calling the API using a POST
request you will send the search criteria in a JSON request body.
Request Body
search.name
StringThe case-insensitive string to search for in the Consent name. This can contain wildcards using the asterisk character (*
). If no wildcards are present, the search criteria will be interpreted as *value*
.
search.numberOfResults
IntegerDefaults to 25The number of results to return from the search.
search.orderBy
StringDefaults to name ASCThe field to order the search results as well as an order direction.
The possible values are:
id
- the unique Id of the ConsentinsertInstant
- the instant when the Consent was createdname
- the Consent name
The order direction is optional. Possible values of the order direction are ASC
or DESC
. If omitted, the default sort order is ASC
.
For example, to order the results by the insert instant in a descending order, use insertInstant DESC
.
search.startRow
IntegerDefaults to 0The offset into the total results. In order to paginate the results, increment this value by the numberOfResults for subsequent requests.
For example, if the total search results are greater than the page size designated by numberOfResults , set this value to 25
to retrieve results 26-50
, assuming the default page size.
Example Request JSON
{
"search": {
"name": "patient",
"numberOfResults": 25,
"orderBy": "insertInstant",
"startRow": 0
}
}
Response
The response for this API contains the Consents matching the search criteria in paginated format and the total number of results matching the search criteria.
Response CodesCode | Description |
---|---|
200 | The request was successful. The response will contain a JSON body. |
400 | The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
Response Body
consents
ArrayThe list of Consent objects.
consents[x].consentEmailTemplateId
UUIDThe Id of the Email Template that is used to send confirmation to the end user.
consents[x].countryMinimumAgeForSelfConsent
Map<Locale, Integer>This property optionally overrides the value provided in defaultMinimumAgeForSelfConsent if a more specific value is defined. This can be useful when the age of self consent varies by country.
For example, consider the following definition:
{
"de": 17
}
If a user has defined their preferred locale to be Germany (de
), the age of self consent defined for Germany will be used instead of the value defined by defaultMinimumAgeForSelfConsent .
consents[x].defaultMinimumAgeForSelfConsent
IntegerThe default age of self consent used when granting this consent to a user unless a more specific one is provided by the countryMinimumAgeForSelfConsent .
A user that meets the minimum age of self consent may self-consent, this means the recipient may also be the giver.
consents[x].emailPlus.enabled
BooleanWhen this value is true
the Email Plus workflow is enabled.
Email Plus provides and additional opportunity to notify the giver that consent was provided. For example, if consentEmailTemplateId is provided then when the consent is granted an email will be sent to notify the giver that consent was granted to the user. When using Email Plus a follow up email will be sent to the giver at a randomly selected time within the configured minimum and maximum range of hours.
consents[x].emailPlus.emailTemplateId
UUIDThe Id of the Email Template that is used to send the reminder notice to the consent giver.
consents[x].emailPlus.maximumTimeToSendEmailInHours
IntegerThe maximum number of hours to wait until sending the reminder notice the consent giver.
consents[x].emailPlus.minimumTimeToSendEmailInHours
IntegerThe minimum number of hours to wait until sending the reminder notice the consent giver.
consents[x].id
UUIDThe unique Id of the consent.
consent[x].insertInstant
LongThe instant that the Consent was added to the FusionAuth database.
consent[x].lastUpdateInstant
LongThe instant that the Consent was updated in the FusionAuth database.
consents[x].multipleValuesAllowed
BooleanWhen this value is true
more than one value may be used when granting this consent to a User.
This value is not used when no values have been defined for this consent.
consents[x].name
StringThe unique name of the consent.
consents[x].values
Array<String>One or more values that may be assigned for this consent.
total
IntegerThe total number of Consents matching the search criteria. Use this value along with the numberOfResults and startRow in the search request to perform pagination.
Example Response JSON
{
"consents": [
{
"consentEmailTemplateId": "61cba163-2d53-4d2d-ad7f-801c27f0c277",
"countryMinimumAgeForSelfConsent": {
"de": 21
},
"defaultMinimumAgeForSelfConsent": 18,
"emailPlus": {
"enabled": true,
"emailTemplateId": "9cd65fca-5aa0-4861-899b-8712d8ec963f",
"maximumTimeToSendEmailInHours": 48,
"minimumTimeToSendEmailInHours": 24
},
"id": "d512b9b8-876f-4b5e-81f0-3e180b6ea485",
"insertInstant": 1595361142909,
"lastUpdateInstant": 1595361143101,
"multipleValuesAllowed": false,
"name": "Patient Consent",
"values": [
"Written",
"Verbal"
]
}
],
"total": 1
}
Grant a User Consent
This API is used to grant Consent to a User.
Request
Request Headers
X-FusionAuth-TenantId
StringThe unique Id of the tenant used to scope this API request.
The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.
Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.
See Making an API request using a Tenant Id for additional information.
Request Parameters
userConsentId
UUIDDefaults to secure random UUIDThe Id to use for the new User Consent. If not specified a secure random UUID will be generated.
Request Headers
X-FusionAuth-TenantId
StringThe unique Id of the tenant used to scope this API request.
The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.
Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.
See Making an API request using a Tenant Id for additional information.
Request Body
userConsent.consentId
UUIDrequiredThe Id of the Consent being granted to the User.
userConsent.giverUserId
UUIDrequiredThe Id of the User giving consent. When providing self-consent the giverUserId will be the same as the userId .
userConsent.status
StringDefaults to ActiveAvailable since 1.43.0The status of the User consent. Possible values are:
Active
Revoked
userConsent.userId
UUIDrequiredThe Id of the User receiving consent. When providing self-consent the giverUserId will be the same as the userId .
userConsent.status
StringrequiredThe status of the User consent. Possible values are: // The spaces before the ’-’ on list items are required to properly align the text after the list
Active
Revoked
Setting the status to Revoked
when the current status is Active
will revoke the User Consent. Setting the status to Active
when the current status is Revoked
will Un-revoke the User Consent and make active again.
userConsent.values
Array<String>The consent values to be associated with this User consent.
Example Request JSON
{
"userConsent": {
"consentId": "d512b9b8-876f-4b5e-81f0-3e180b6ea485",
"giverUserId": "605e88b7-a2fb-40b8-9c94-0123c0f6a70c",
"userId": "841d8b33-bf4d-488d-9f2f-2f50d769c3d2",
"values": [
"Written"
]
}
}
Response
The response for this API contains the User Consent that was created.
Response CodesCode | Description |
---|---|
200 | The request was successful. The response will contain a JSON body. |
400 | The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |
Response Body
userConsent.consent
ObjectThe Consent object represented by the consentId field.
userConsent.consentId
UUIDThe Id of the Consent being granted to the User.
userConsent.giverUserId
UUIDThe Id of the User giving consent. When providing self-consent the giverUserId will be the same as the userId .
userConsent.id
UUIDThe unique Id of the User consent.
userConsent.insertInstant
LongThe instant when the User consent was granted.
userConsent.lastUpdateInstant
LongThe instant when the User consent was last updated.
userConsent.status
StringThe current status of the User consent. Possible values are:
Active
Revoked
userConsent.userId
UUIDThe Id of the User receiving consent. When providing self-consent the giverUserId will be the same as the userId .
userConsent.values
Array<String>The consent values to be associated with this User consent.
Example Response JSON
{
"userConsent": {
"consent": {
"consentEmailTemplateId": "61cba163-2d53-4d2d-ad7f-801c27f0c277",
"countryMinimumAgeForSelfConsent": {
"de": 21
},
"defaultMinimumAgeForSelfConsent": 18,
"emailPlus": {
"enabled": true,
"emailTemplateId": "9cd65fca-5aa0-4861-899b-8712d8ec963f",
"maximumTimeToSendEmailInHours": 48,
"minimumTimeToSendEmailInHours": 24
},
"id": "d512b9b8-876f-4b5e-81f0-3e180b6ea485",
"multipleValuesAllowed": false,
"name": "Patient Consent",
"values": [
"Written",
"Verbal"
]
},
"consentId": "d512b9b8-876f-4b5e-81f0-3e180b6ea485",
"giverUserId": "605e88b7-a2fb-40b8-9c94-0123c0f6a70c",
"id": "674b5cd8-482a-43c9-986e-f9764bbee01d",
"insertInstant": 1562180786558,
"lastUpdateInstant": 1562180786558,
"status": "Active",
"userId": "841d8b33-bf4d-488d-9f2f-2f50d769c3d2",
"values": [
"Written"
]
}
}
Retrieve a User Consent
This API is used to retrieve a single User Consent by unique Id or all of User’s Consents by user Id.
Request
Request Parameters
userId
UUIDThe unique Id of the User to retrieve User Consents for.
userConsentId
UUIDThe unique Id of the User Consent to retrieve.
Response
The response for this API contains either a single User Consent or all of a User’s Consents. When you call this API with an Id the response will contain a single Consent. When you call this API with the userId
query parameter, the response will contain all of the User’s Consents. Both response types are defined below along with an example JSON response.
Code | Description |
---|---|
200 | The request was successful. The response will contain a JSON body. |
400 | The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
404 | The object you requested doesn't exist. The response will be empty. |
500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |
Response Body
userConsent.consent
ObjectThe Consent object represented by the consentId field.
userConsent.consentId
UUIDThe Id of the Consent being granted to the User.
userConsent.giverUserId
UUIDThe Id of the User giving consent. When providing self-consent the giverUserId will be the same as the userId .
userConsent.id
UUIDThe unique Id of the User consent.
userConsent.insertInstant
LongThe instant when the User consent was granted.
userConsent.lastUpdateInstant
LongThe instant when the User consent was last updated.
userConsent.status
StringThe current status of the User consent. Possible values are:
Active
Revoked
userConsent.userId
UUIDThe Id of the User receiving consent. When providing self-consent the giverUserId will be the same as the userId .
userConsent.values
Array<String>The consent values to be associated with this User consent.
Example Response JSON
{
"userConsent": {
"consent": {
"consentEmailTemplateId": "61cba163-2d53-4d2d-ad7f-801c27f0c277",
"countryMinimumAgeForSelfConsent": {
"de": 21
},
"defaultMinimumAgeForSelfConsent": 18,
"emailPlus": {
"enabled": true,
"emailTemplateId": "9cd65fca-5aa0-4861-899b-8712d8ec963f",
"maximumTimeToSendEmailInHours": 48,
"minimumTimeToSendEmailInHours": 24
},
"id": "d512b9b8-876f-4b5e-81f0-3e180b6ea485",
"multipleValuesAllowed": false,
"name": "Patient Consent",
"values": [
"Written",
"Verbal"
]
},
"consentId": "d512b9b8-876f-4b5e-81f0-3e180b6ea485",
"giverUserId": "605e88b7-a2fb-40b8-9c94-0123c0f6a70c",
"id": "674b5cd8-482a-43c9-986e-f9764bbee01d",
"insertInstant": 1562180786558,
"lastUpdateInstant": 1562180786558,
"status": "Active",
"userId": "841d8b33-bf4d-488d-9f2f-2f50d769c3d2",
"values": [
"Written"
]
}
}
Response Body
userConsents[x].consent
ObjectThe Consent object represented by the consentId field.
userConsents[x].consentId
UUIDThe Id of the Consent being granted to the User.
userConsents[x].giverUserId
UUIDThe Id of the User giving consent. When providing self-consent the giverUserId will be the same as the userId .
userConsents[x].id
UUIDThe unique Id of the User consent.
userConsents[x].insertInstant
LongThe instant when the User consent was granted.
userConsents[x].lastUpdateInstant
LongThe instant when the User consent was last updated.
userConsents[x].status
StringThe current status of the User consent. Possible values are:
Active
Revoked
userConsents[x].userId
UUIDThe Id of the User receiving consent. When providing self-consent the giverUserId will be the same as the userId .
userConsents[x].values
Array<String>The consent values to be associated with this User consent.
Example Response JSON
{
"userConsents": [
{
"consent": {
"consentEmailTemplateId": "61cba163-2d53-4d2d-ad7f-801c27f0c277",
"countryMinimumAgeForSelfConsent": {
"de": 21
},
"defaultMinimumAgeForSelfConsent": 18,
"emailPlus": {
"enabled": true,
"emailTemplateId": "9cd65fca-5aa0-4861-899b-8712d8ec963f",
"maximumTimeToSendEmailInHours": 48,
"minimumTimeToSendEmailInHours": 24
},
"id": "d512b9b8-876f-4b5e-81f0-3e180b6ea485",
"multipleValuesAllowed": false,
"name": "Patient Consent",
"values": [
"Written",
"Verbal"
]
},
"consentId": "d512b9b8-876f-4b5e-81f0-3e180b6ea485",
"giverUserId": "605e88b7-a2fb-40b8-9c94-0123c0f6a70c",
"id": "674b5cd8-482a-43c9-986e-f9764bbee01d",
"insertInstant": 1562180786558,
"lastUpdateInstant": 1562180786558,
"status": "Active",
"userId": "841d8b33-bf4d-488d-9f2f-2f50d769c3d2",
"values": [
"Written"
]
}
]
}
Update a User Consent
This API is used to update a consent. Once consent has been granted to a User, only the values and status may be modified.
Request
Request Parameters
userConsentId
UUIDrequiredThe Id of the User Consent to update.
Request Headers
X-FusionAuth-TenantId
StringThe unique Id of the tenant used to scope this API request.
The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.
Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.
See Making an API request using a Tenant Id for additional information.
Request Body
userConsent.status
StringrequiredThe status of the User consent. Possible values are: // The spaces before the ’-’ on list items are required to properly align the text after the list
Active
Revoked
Setting the status to Revoked
when the current status is Active
will revoke the User Consent. Setting the status to Active
when the current status is Revoked
will Un-revoke the User Consent and make active again.
userConsent.values
Array<String>The consent values to be associated with this User consent.
Example Request JSON
{
"userConsent": {
"status": "Active",
"values": [
"Verbal"
]
}
}
Response
The response for this API contains the User Consent that was updated.
Response CodesCode | Description |
---|---|
200 | The request was successful. The response will contain a JSON body. |
400 | The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
404 | The object you are trying to update doesn't exist. The response will be empty. |
500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |
Response Body
userConsent.consent
ObjectThe Consent object represented by the consentId field.
userConsent.consentId
UUIDThe Id of the Consent being granted to the User.
userConsent.giverUserId
UUIDThe Id of the User giving consent. When providing self-consent the giverUserId will be the same as the userId .
userConsent.id
UUIDThe unique Id of the User consent.
userConsent.insertInstant
LongThe instant when the User consent was granted.
userConsent.lastUpdateInstant
LongThe instant when the User consent was last updated.
userConsent.status
StringThe current status of the User consent. Possible values are:
Active
Revoked
userConsent.userId
UUIDThe Id of the User receiving consent. When providing self-consent the giverUserId will be the same as the userId .
userConsent.values
Array<String>The consent values to be associated with this User consent.
Example Response JSON
{
"userConsent": {
"consent": {
"consentEmailTemplateId": "61cba163-2d53-4d2d-ad7f-801c27f0c277",
"countryMinimumAgeForSelfConsent": {
"de": 21
},
"defaultMinimumAgeForSelfConsent": 18,
"emailPlus": {
"enabled": true,
"emailTemplateId": "9cd65fca-5aa0-4861-899b-8712d8ec963f",
"maximumTimeToSendEmailInHours": 48,
"minimumTimeToSendEmailInHours": 24
},
"id": "d512b9b8-876f-4b5e-81f0-3e180b6ea485",
"multipleValuesAllowed": false,
"name": "Patient Consent",
"values": [
"Written",
"Verbal"
]
},
"consentId": "d512b9b8-876f-4b5e-81f0-3e180b6ea485",
"giverUserId": "605e88b7-a2fb-40b8-9c94-0123c0f6a70c",
"id": "674b5cd8-482a-43c9-986e-f9764bbee01d",
"insertInstant": 1562180786558,
"lastUpdateInstant": 1562180786558,
"status": "Active",
"userId": "841d8b33-bf4d-488d-9f2f-2f50d769c3d2",
"values": [
"Written"
]
}
}
Revoke a User Consent
This API is used to revoke a consent. This is equivalent to using the Update User Consent API and modifying the status to Revoked
.
Request
Request Headers
X-FusionAuth-TenantId
StringThe unique Id of the tenant used to scope this API request.
The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.
Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.
See Making an API request using a Tenant Id for additional information.
Response
This API does not return a JSON response body.
Response CodesCode | Description |
---|---|
200 | The request was successful. |
400 | The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
404 | The object you requested doesn't exist. The response will be empty. |
500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |