Logo / Docs

Families

Overview

This API has been available since 1.7.0

A Family allows you to define relationships between one or more Users. A adult User may belong to a single Family, a teen or child may belong to one or more families.

The following APIs are provided to manage Families and Family memberships.

Add a User to a Family

This API is used to add a User to a Family. You cannot directly create a family, instead a family is implicitly created when the first User is added.

Request

API Key Authentication
Add a User to a Family with a randomly generated Id
POST /api/user/family

Request Headers

X-FusionAuth-TenantIdString

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.

API Key Authentication
Add a User to a Family with the provided unique Id
POST /api/user/family/{familyId}

Request Parameters

familyIdUUIDDefaults to secure random UUID

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

Request Headers

X-FusionAuth-TenantIdString

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

familyMember.userIdUUIDrequired

The unique userId of the User to add to a family.

familyMember.ownerBooleanDefaults to false

Set to true to indicate a family owner. This value will be ignored if the user role is Teen or Child.

familyMember.roleStringrequired

The role of the user in the family.

When creating a family the first user must be an adult. This value must be set to Adult.

Example Request JSON

{
  "familyMember": {
    "userId": "b3360a2d-e81d-4314-b9f1-244a916ca52f",
    "owner": true,
    "role": "Adult"
  }
}

Response

The response for this API contains the Family that was created.

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

family.idUUID

The unique Id of the family.

family.insertInstantLong

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

family.lastUpdateInstantLong

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

family.membersArray<Object>

The members of this family.

family.members[x].insertInstantLong

The instant when the user was added to the family.

families.members[x].lastUpdateInstantLong

The instant when the family member was last updated.

family.members[x].ownerBoolean

True if this user is the owner of the family, the first Adult user in the family will automatically be set as the owner. A teen or child cannot be the family owner.

family.members[x].roleString

The role of the family member.

The possible values are:
  • Adult
  • Child
  • Teen
family.members[x].userIdUUID

The unique user Id of the family member.

Example Response JSON

{
  "family": {
    "id": "a815b480-d52d-4755-96ac-749c067925d7",
    "insertInstant": 1595361142909,
    "lastUpdateInstant": 1595361143101,
    "members": [
      {
        "insertInstant": 1562010348111,
        "lastUpdateInstant": 1595361143101,
        "owner": true,
        "role": "Adult",
        "userId": "b3360a2d-e81d-4314-b9f1-244a916ca52f"
      }
    ]
  }
}

Retrieve a Family

This API is used to retrieve a Family by a User Id or by Family Id.

Request

API Key Authentication
Retrieve a Family by Id
GET /api/user/family/{familyId}

Request Parameters

familyIdUUIDrequired

The unique Id of the Family.

Request Headers

X-FusionAuth-TenantIdString

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

API Key Authentication
Retrieve all of a User's families by User Id
GET /api/user/family?userId={userId}

Request Parameters

userIdUUIDrequired

The unique Id of the User.

Request Headers

X-FusionAuth-TenantIdString

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.

The response for this API contains the requested family or families.

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

family.idUUID

The unique Id of the family.

family.insertInstantLong

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

family.lastUpdateInstantLong

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

family.membersArray<Object>

The members of this family.

family.members[x].insertInstantLong

The instant when the user was added to the family.

families.members[x].lastUpdateInstantLong

The instant when the family member was last updated.

family.members[x].ownerBoolean

True if this user is the owner of the family, the first Adult user in the family will automatically be set as the owner. A teen or child cannot be the family owner.

family.members[x].roleString

The role of the family member.

The possible values are:
  • Adult
  • Child
  • Teen
family.members[x].userIdUUID

The unique user Id of the family member.

Example Response JSON

{
  "family": {
    "id": "a815b480-d52d-4755-96ac-749c067925d7",
    "insertInstant": 1595361142909,
    "lastUpdateInstant": 1595361143101,
    "members": [
      {
        "insertInstant": 1562010348111,
        "lastUpdateInstant": 1595361143101,
        "owner": true,
        "role": "Adult",
        "userId": "b3360a2d-e81d-4314-b9f1-244a916ca52f"
      }
    ]
  }
}

Response Body

familiesArray<Object>

The list of Family objects.

families[x].idUUID

The unique Id of the family.

families[x].insertInstantLong

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

families[x].lastUpdateInstantLong

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

families[x].membersArray<Object>

The members of this family.

families[x].members[x].insertInstantLong

The instant when the user was added to the family.

families[x].members[x].lastUpdateInstantLong

The instant when the family member was last updated.

families[x].members[x].ownerBoolean

True if this user is the owner of the family, the first Adult user in the family will automatically be set as the owner. A teen or child cannot be the family owner.

families[x].members[x].roleString

The role of the family member. The possible values are:

  • Adult
  • Child
  • Teen
families[x].members[x].userIdUUID

The unique user Id of the family member.

Example Response JSON

{
  "families": [
    {
      "id": "a815b480-d52d-4755-96ac-749c067925d7",
      "insertInstant": 1595361142909,
      "lastUpdateInstant": 1595361143101,
      "members": [
        {
          "insertInstant": 1562010348111,
          "lastUpdateInstant": 1595361143101,
          "owner": true,
          "role": "Adult",
          "userId": "b3360a2d-e81d-4314-b9f1-244a916ca52f"
        }
      ]
    }
  ]
}

Update a Family

This API is used to update an existing Family member. You may only update the User’s role or owner status.

Request

API Key Authentication
Update a Family member
PUT /api/user/family/{familyId}

Request Parameters

familyIdUUIDrequired

The unique Id of the Family.

Request Headers

X-FusionAuth-TenantIdString

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

familyMember.userIdUUIDrequired

The unique userId of the User to add to a family.

familyMember.ownerBooleanDefaults to false

Set to true to indicate a family owner. This value will be ignored if the user role is Teen or Child.

familyMember.roleStringrequired

The role of the user in the family.

The possible values are:
  • Adult
  • Child
  • Teen

Example Request JSON

{
  "familyMember": {
    "userId": "b3360a2d-e81d-4314-b9f1-244a916ca52f",
    "owner": true,
    "role": "Adult"
  }
}

Response

The response for this API contains the Family that was updated.

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

family.idUUID

The unique Id of the family.

family.insertInstantLong

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

family.lastUpdateInstantLong

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

family.membersArray<Object>

The members of this family.

family.members[x].insertInstantLong

The instant when the user was added to the family.

families.members[x].lastUpdateInstantLong

The instant when the family member was last updated.

family.members[x].ownerBoolean

True if this user is the owner of the family, the first Adult user in the family will automatically be set as the owner. A teen or child cannot be the family owner.

family.members[x].roleString

The role of the family member.

The possible values are:
  • Adult
  • Child
  • Teen
family.members[x].userIdUUID

The unique user Id of the family member.

Example Response JSON

{
  "family": {
    "id": "a815b480-d52d-4755-96ac-749c067925d7",
    "insertInstant": 1595361142909,
    "lastUpdateInstant": 1595361143101,
    "members": [
      {
        "insertInstant": 1562010348111,
        "lastUpdateInstant": 1595361143101,
        "owner": true,
        "role": "Adult",
        "userId": "b3360a2d-e81d-4314-b9f1-244a916ca52f"
      }
    ]
  }
}

Remove a User from a Family

This API is used to remove a User from an existing Family.

Request

API Key Authentication
Remove a User from a Family
DELETE /api/user/family/{familyId}/{userId}

Request Parameters

familyIdUUIDrequired

The unique Id of the Family.

userIdUUIDrequired

The unique Id of the User.

Request Headers

X-FusionAuth-TenantIdString

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.

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.

Retrieve Pending Family Members

This API is used to retrieve the users pending parent approval.

Request

API Key Authentication
Retrieve pending users by parent email address
GET /api/user/family/pending?parentEmail={parentEmail}

Request Parameters

parentEmailStringrequired

The email address of the parent.

Request Headers

X-FusionAuth-TenantIdString

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

The response for this API contains the requested pending users.

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

users[x].activeBoolean

True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login.

users[x].birthDateString

The User’s birthdate formatted as YYYY-MM-DD

users[x].dataObject

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

users[x].emailString

The User’s email address.

users[x].fullNameString

The User’s full name as a separate field that is not calculated from firstName and lastName .

users[x].idUUID

The User’s unique Id.

users[x].insertInstantLong

The instant when the user was created.

users[x].parentEmailString

The user’s parent’s email address.

users[x].passwordChangeRequiredBoolean

Indicates that the User’s password needs to be changed during their next login attempt.

users[x].passwordLastUpdateInstantLong

The instant that the User last changed their password.

users[x].preferredLanguagesArray<String>

An array of locale strings that give, in order, the User’s preferred languages. These are important for email templates and other localizable text. See Locales.

users[x].tenantIdUUID

The Id of the Tenant that this User belongs to.

users[x].timezoneString

The User’s preferred timezone. This can be used as a default to display instants, and it is recommended that you allow User’s to change this per-session. The string will be in an IANA time zone format.

users[x].twoFactor.methods[x].authenticator.algorithmString

The algorithm used by the TOTP authenticator. With the current implementation, this will always be HmacSHA1.

users[x].twoFactor.methods[x].authenticator.codeLengthInteger

The length of code generated by the TOTP. With the current implementation, this will always be 6.

users[x].twoFactor.methods[x].authenticator.timeStepInteger

The time-step size in seconds. With the current implementation, this will always be 30.

users[x].twoFactor.methods[x].emailString

The value of the email address for this method. Only present if user.twoFactor.methods[x].method is email.

users[x].twoFactor.methods[x].idString

The unique Id of the method.

users[x].twoFactor.methods[x].lastUsedBoolean

true if this method was used most recently.

users[x].twoFactor.methods[x].methodString

The type of this method. There will also be an object with the same value containing additional information about this method. The possible values are:

  • authenticator
  • email
  • sms
users[x].twoFactor.methods[x].mobilePhoneString

The value of the mobile phone for this method. Only present if user.twoFactor.methods[x].method is sms.

users[x].twoFactor.recoveryCodesArray<String>

A list of recovery codes. These may be used in place of a code provided by an MFA factor. They are single use.

If a recovery code is used in a disable request, all MFA methods are removed. If, after that, a Multi-Factor method is added, a new set of recovery codes will be generated.

users[x].twoFactorDeliveryStringDEPRECATED

The User’s preferred delivery for verification codes during a two factor login request.

The possible values are:

  • None
  • TextMessage
users[x].twoFactorEnabledBooleanDEPRECATED

Determines if the User has two factor authentication enabled for their account or not.

Removed in 1.26.0
users[x].usernameString

The username of the User.

users[x].usernameStatusString

The current status of the username. This is used if you are moderating usernames via CleanSpeak. The possible values are:

  • ACTIVE - the username is active
  • PENDING - the username is pending approval/moderation
  • REJECTED - the username was rejected during moderation

If a username has been rejected, it is still possible to allow the User to update it and have the new one moderated again.

users[x].verifiedBoolean

Whether or not the User’s email has been verified.

Example Response JSON

{
  "users": [
    {
      "active": true,
      "birthDate": "2009-10-31",
      "data": {
        "attr1": "value1",
        "attr2": [
          "value2",
          "value3"
        ]
      },
      "email": "somekid@piedpiper.com",
      "fullName": "Kid A",
      "id": "00000000-0000-0001-0000-000000000003",
      "insertInstant": 1572551641422,
      "parentEmail": "somekidsparent@piedpiper.com",
      "passwordChangeRequired": false,
      "passwordLastUpdateInstant": 1572551641422,
      "preferredLanguages": [
        "en",
        "fr"
      ],
      "tenantId": "64653766-6162-6234-3036-393935316533",
      "timezone": "America/Denver",
      "twoFactorDelivery": "None",
      "twoFactorEnabled": false,
      "username": "somekid",
      "usernameStatus": "ACTIVE",
      "verified": true
    }
  ]
}

Request Parental Approval

This API is used to send an email requesting parental approval for a child registration using the configured tenant.familyConfiguration.familyRequestEmailTemplateId.

Request

API Key Authentication
Request parental approval
POST /api/user/family/request

Request Headers

X-FusionAuth-TenantIdString

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

parentEmailStringrequired

The email address of the parent.

Example Request JSON

{
  "parentEmail": "somekidsparent@piedpiper.com"
}

Response

This API does not return a JSON response body.

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.