Consent APIs

    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.

    Related Posts

    This API is used to create a new Consent.

    Request

    Create a new Consent with a randomly generated Id

    URI

    POST /api/consent

    Create a new Consent with the provided unique Id

    URI

    POST /api/consent/{consentId}

    Request Parameters

    consentId [UUID] Optional defaults to secure random UUID

    The Id to use for the new Consent. If not specified a secure random UUID will be generated.

    Request Body

    consent.consentEmailTemplateId [UUID] Optional

    The 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>] Optional

    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 [Object] Optional

    An object that can hold any information about the Consent that should be persisted.

    consent.defaultMinimumAgeForSelfConsent [Integer] Required

    The 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 [Boolean] Optional defaults to false

    Set 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 [UUID] Required

    The 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 [Integer] Optional defaults to 48

    The maximum number of hours to wait until sending the reminder notice the consent giver.

    consent.emailPlus.minimumTimeToSendEmailInHours [Integer] Optional defaults to 24

    The minimum number of hours to wait until sending the reminder notice the consent giver.

    consent.multipleValuesAllowed [Boolean] Optional defaults to false

    Set 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 [String] Required

    The unique name of the consent.

    consent.values [Array<String>] Optional

    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.

    Table 1. Response Codes
    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.

    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 [UUID]

    The 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 [Object]

    An object that can hold any information about the Consent that should be persisted.

    consent.defaultMinimumAgeForSelfConsent [Integer]

    The 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 [Boolean]

    When 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 [UUID]

    The Id of the Email Template that is used to send the reminder notice to the consent giver.

    consent.emailPlus.maximumTimeToSendEmailInHours [Integer]

    The maximum number of hours to wait until sending the reminder notice the consent giver.

    consent.emailPlus.minimumTimeToSendEmailInHours [Integer]

    The minimum number of hours to wait until sending the reminder notice the consent giver.

    consent.id [UUID]

    The unique Id of the consent.

    consent.insertInstant [Long]

    The instant that the Consent was added to the FusionAuth database.

    consent.lastUpdateInstant [Long]

    The instant that the Consent was updated in the FusionAuth database.

    consent.multipleValuesAllowed [Boolean]

    When 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 [String]

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

    This API is used to retrieve a single Consent by unique Id or all of the configured Consents.

    Request

    Retrieve all of the Consents

    URI

    GET /api/consent

    Retrieve a Consent by Id

    URI

    GET /api/consent/{consentId}

    Request Parameters

    consentId [UUID] Required

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

    Table 2. Response Codes
    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

    consent.consentEmailTemplateId [UUID]

    The 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 [Object]

    An object that can hold any information about the Consent that should be persisted.

    consent.defaultMinimumAgeForSelfConsent [Integer]

    The 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 [Boolean]

    When 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 [UUID]

    The Id of the Email Template that is used to send the reminder notice to the consent giver.

    consent.emailPlus.maximumTimeToSendEmailInHours [Integer]

    The maximum number of hours to wait until sending the reminder notice the consent giver.

    consent.emailPlus.minimumTimeToSendEmailInHours [Integer]

    The minimum number of hours to wait until sending the reminder notice the consent giver.

    consent.id [UUID]

    The unique Id of the consent.

    consent.insertInstant [Long]

    The instant that the Consent was added to the FusionAuth database.

    consent.lastUpdateInstant [Long]

    The instant that the Consent was updated in the FusionAuth database.

    consent.multipleValuesAllowed [Boolean]

    When 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 [String]

    The 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 [Array]

    The list of Consent objects.

    consents[x].consentEmailTemplateId [UUID]

    The 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 [Integer]

    The 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 [Boolean]

    When 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 [UUID]

    The Id of the Email Template that is used to send the reminder notice to the consent giver.

    consents[x].emailPlus.maximumTimeToSendEmailInHours [Integer]

    The maximum number of hours to wait until sending the reminder notice the consent giver.

    consents[x].emailPlus.minimumTimeToSendEmailInHours [Integer]

    The minimum number of hours to wait until sending the reminder notice the consent giver.

    consents[x].id [UUID]

    The unique Id of the consent.

    consent[x].insertInstant [Long]

    The instant that the Consent was added to the FusionAuth database.

    consent[x].lastUpdateInstant [Long]

    The instant that the Consent was updated in the FusionAuth database.

    consents[x].multipleValuesAllowed [Boolean]

    When 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 [String]

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

    This API is used to update an existing Consent.

    You must specify the Id of the Consent you are updating on the URI.

    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

    Update the Consent with the given Id

    URI

    PUT /api/consent/{consentId}

    PATCH /api/consent/{consentId}

    Available since 1.39.0

    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.

    Available since 1.12.0

    When using the PATCH method, use the same request body documentation that is provided for the PUT request. The PATCH method will merge the provided request parameters 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 [UUID] Required

    The Id to use for the Consent to update.

    Request Body

    consent.consentEmailTemplateId [UUID] Optional

    The 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>] Optional

    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 [Object] Optional

    An object that can hold any information about the Consent that should be persisted.

    consent.defaultMinimumAgeForSelfConsent [Integer] Required

    The 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 [Boolean] Optional defaults to false

    Set 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 [UUID] Required

    The 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 [Integer] Optional defaults to 48

    The maximum number of hours to wait until sending the reminder notice the consent giver.

    consent.emailPlus.minimumTimeToSendEmailInHours [Integer] Optional defaults to 24

    The minimum number of hours to wait until sending the reminder notice the consent giver.

    consent.multipleValuesAllowed [Boolean] Optional defaults to false

    Set 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 [String] Required

    The unique name of the consent.

    consent.values [Array<String>] Optional

    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.

    Table 3. Response Codes
    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 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 [UUID]

    The 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 [Object]

    An object that can hold any information about the Consent that should be persisted.

    consent.defaultMinimumAgeForSelfConsent [Integer]

    The 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 [Boolean]

    When 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 [UUID]

    The Id of the Email Template that is used to send the reminder notice to the consent giver.

    consent.emailPlus.maximumTimeToSendEmailInHours [Integer]

    The maximum number of hours to wait until sending the reminder notice the consent giver.

    consent.emailPlus.minimumTimeToSendEmailInHours [Integer]

    The minimum number of hours to wait until sending the reminder notice the consent giver.

    consent.id [UUID]

    The unique Id of the consent.

    consent.insertInstant [Long]

    The instant that the Consent was added to the FusionAuth database.

    consent.lastUpdateInstant [Long]

    The instant that the Consent was updated in the FusionAuth database.

    consent.multipleValuesAllowed [Boolean]

    When 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 [String]

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

    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

    Delete a Consent by Id

    URI

    DELETE /api/consent/{consentId}

    Request Parameters

    consentId [UUID] Required

    The unique Id of the Consent to delete.

    Response

    This API does not return a JSON response body.

    Table 4. Response Codes
    Code Description

    200

    The request was successful. The response will be empty.

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

    This API is used to grant Consent to a User.

    Request

    Grant consent to a User with a randomly generated Id

    URI

    POST /api/user/consent

    Request Headers

    X-FusionAuth-TenantId [String] Optional

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

    Grant consent to a User with the provided unique Id

    URI

    POST /api/user/consent/{userConsentId}

    Request Parameters

    userConsentId [UUID] Optional defaults to secure random UUID

    The Id to use for the new User Consent. If not specified a secure random UUID will be generated.

    Request Headers

    X-FusionAuth-TenantId [String] Optional

    The 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 [UUID] Required

    The Id of the Consent being granted to the User.

    userConsent.giverUserId [UUID] Required

    The Id of the User giving consent. When providing self-consent the giverUserId will be the same as the userId.

    userConsent.status [String] Optional defaults to Active Available since 1.43.0

    The status of the User consent. Possible values are:

    • Active

    • Revoked

    userConsent.userId [UUID] Required

    The Id of the User receiving consent. When providing self-consent the giverUserId will be the same as the userId.

    userConsent.values [Array<String>] Optional

    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.

    Table 5. Response Codes
    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.

    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 [Object]

    The Consent object represented by the consentId field.

    userConsent.consentId [UUID]

    The Id of the Consent being granted to the User.

    userConsent.giverUserId [UUID]

    The Id of the User giving consent. When providing self-consent the giverUserId will be the same as the userId.

    userConsent.id [UUID]

    The unique Id of the User consent.

    userConsent.insertInstant [Long]

    The instant when the User consent was granted.

    userConsent.lastUpdateInstant [Long]

    The instant when the User consent was last updated.

    userConsent.status [String]

    The current status of the User consent. Possible values are:

    • Active

    • Revoked

    userConsent.userId [UUID]

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

    This API is used to retrieve a single User Consent by unique Id or all of User’s Consents by user Id.

    Request

    Retrieve all of a User’s Consents

    URI

    GET /api/user/consent?userId={uuid}

    Retrieve a User Consent by Id

    URI

    GET /api/user/consent/{userConsentId}

    Request Parameters

    userId [UUID] Optional

    The unique Id of the User to retrieve User Consents for.

    userConsentId [UUID] Optional

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

    Table 6. Response Codes
    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 [Object]

    The Consent object represented by the consentId field.

    userConsent.consentId [UUID]

    The Id of the Consent being granted to the User.

    userConsent.giverUserId [UUID]

    The Id of the User giving consent. When providing self-consent the giverUserId will be the same as the userId.

    userConsent.id [UUID]

    The unique Id of the User consent.

    userConsent.insertInstant [Long]

    The instant when the User consent was granted.

    userConsent.lastUpdateInstant [Long]

    The instant when the User consent was last updated.

    userConsent.status [String]

    The current status of the User consent. Possible values are:

    • Active

    • Revoked

    userConsent.userId [UUID]

    The 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 [Object]

    The Consent object represented by the consentId field.

    userConsents[x].consentId [UUID]

    The Id of the Consent being granted to the User.

    userConsents[x].giverUserId [UUID]

    The Id of the User giving consent. When providing self-consent the giverUserId will be the same as the userId.

    userConsents[x].id [UUID]

    The unique Id of the User consent.

    userConsents[x].insertInstant [Long]

    The instant when the User consent was granted.

    userConsents[x].lastUpdateInstant [Long]

    The instant when the User consent was last updated.

    userConsents[x].status [String]

    The current status of the User consent. Possible values are:

    • Active

    • Revoked

    userConsents[x].userId [UUID]

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

    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

    Update a User Consent with given Id

    URI

    PUT /api/user/consent/{userConsentId}

    PATCH /api/user/consent/{userConsentId}

    Available since 1.39.0

    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.

    Available since 1.12.0

    When using the PATCH method, use the same request body documentation that is provided for the PUT request. The PATCH method will merge the provided request parameters 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

    userConsentId [UUID] Required

    The Id of the User Consent to update.

    Request Headers

    X-FusionAuth-TenantId [String] Optional

    The 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 [String] Required

    The status of the User consent. Possible values are:

    • 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>] Optional

    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.

    Table 7. Response Codes
    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 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 [Object]

    The Consent object represented by the consentId field.

    userConsent.consentId [UUID]

    The Id of the Consent being granted to the User.

    userConsent.giverUserId [UUID]

    The Id of the User giving consent. When providing self-consent the giverUserId will be the same as the userId.

    userConsent.id [UUID]

    The unique Id of the User consent.

    userConsent.insertInstant [Long]

    The instant when the User consent was granted.

    userConsent.lastUpdateInstant [Long]

    The instant when the User consent was last updated.

    userConsent.status [String]

    The current status of the User consent. Possible values are:

    • Active

    • Revoked

    userConsent.userId [UUID]

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

    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

    Revoke a User Consent with given Id

    URI

    DELETE /api/user/consent/{userConsentId}

    Request Headers

    X-FusionAuth-TenantId [String] Optional

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

    Table 8. Response Codes
    Code Description

    200

    The request was successful. The response will be empty.

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

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    Have a question or comment to share?

    Visit the FusionAuth community forum.