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#

Search for Consents

Request Parameters#

nameStringoptional

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

numberOfResultsIntegeroptionalDefaults to 25

The number of results to return from the search.

orderByStringoptionalDefaults to name ASC

The field to order the search results as well as an order direction.

The possible values are:

id - the unique Id of the Consent
insertInstant - the instant when the Consent was created
name - 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.

startRowIntegeroptionalDefaults to 0

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

Search for Consents

OpenAPI Spec

When calling the API using a POST request you will send the search criteria in a JSON request body.

Request Body#

search.nameStringoptional

search.numberOfResultsIntegeroptionalDefaults to 25

The number of results to return from the search.

search.orderByStringoptionalDefaults to name ASC

The field to order the search results as well as an order direction.

The possible values are:

id - the unique Id of the Consent
insertInstant - the instant when the Consent was created
name - 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.startRowIntegeroptionalDefaults to 0

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

Response Body#

consentsArray

The list of Consent objects.

consents[x].consentEmailTemplateIdUUID

The Id of the Email Template that is used to send confirmation to the end user.

consents[x].countryMinimumAgeForSelfConsentMap<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].defaultMinimumAgeForSelfConsentInteger

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

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

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

consents[x].emailPlus.maximumTimeToSendEmailInHoursInteger

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

consents[x].emailPlus.minimumTimeToSendEmailInHoursInteger

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

consents[x].idUUID

The unique Id of the consent.

consent[x].insertInstantLong

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

consent[x].lastUpdateInstantLong

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

consents[x].multipleValuesAllowedBoolean

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].nameString

The unique name of the consent.

consents[x].valuesArray<String>

One or more values that may be assigned for this consent.

totalInteger

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