Family APIs - Home - FusionAuth

1. 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
Retrieve a Family
Update a Family
Remove a User from a Family
Retrieve Pending Family Members
Request Parental Approval

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

2.1. Request

Add a User to a Family with a randomly generated Id

URI

POST /api/user/family

Add a User to a Family with the provided unique Id

URI

POST /api/user/family/{familyId}

Table 1. Request Parameters
familyId [UUID] Optional defaults to secure random UUID	The Id to use for the new Family. If not specified a secure random UUID will be generated.

Table 2. Request Body
familyMember.userId [UUID] Required	The unique userId of the User to add to a family.
familyMember.owner [Boolean] Optional defaults to `false`	Set to `true` to indicate a family owner. This value will be ignored if the user role is `Teen` or `Child`.
familyMember.role [String] Required	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"
  }
}

2.2. Response

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

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

Table 4. Response Body when retrieving a Family by Id
family.id [UUID]	The unique Id of the family.
family.members [Array<Object>]	The members of this family.
family.members`[x]`.insertInstant [Long]	The instant when the user was added to the family.
family.members`[x]`.owner [Boolean]	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]`.role [String]	The role of the family member. The possible values are: `Adult` `Child` `Teen`
family.members`[x]`.userId [UUID]	The unique user Id of the family member.

Example Response JSON

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

3. Retrieve a Family

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

3.1. Request

Retrieve a Family by Id

URI

GET /api/user/family/{familyId}

Table 5. Request Parameters
familyId [UUID] Required	The unique Id of the Family.

3.2. Request

Retrieve all of a User’s families by User Id

URI

GET /api/user/family?userId={userId}

Table 6. Request Parameters
userId [UUID] Required	The unique Id of the User.

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

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

Table 8. Response Body when retrieving a Family by Id
family.id [UUID]	The unique Id of the family.
family.members [Array<Object>]	The members of this family.
family.members`[x]`.insertInstant [Long]	The instant when the user was added to the family.
family.members`[x]`.owner [Boolean]	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]`.role [String]	The role of the family member. The possible values are: `Adult` `Child` `Teen`
family.members`[x]`.userId [UUID]	The unique user Id of the family member.

Example Response JSON

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

Table 9. Response Body when retrieving families by User Id
families [Array<Object>]	The list of Family objects.
families`[x]`.id [UUID]	The unique Id of the family.
families`[x]`.members [Array<Object>]	The members of this family.
families`[x]`.members`[x]`.insertInstant [Long]	The instant when the user was added to the family.
families`[x]`.members`[x]`.owner [Boolean]	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]`.role [String]	The role of the family member. The possible values are: `Adult` `Child` `Teen`
families`[x]`.members`[x]`.userId [UUID]	The unique user Id of the family member.

Example Response JSON

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

4. Update a Family

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

4.1. Request

Update a Family member

URI

PUT /api/user/family/{familyId}

Table 10. Request Parameters
familyId [UUID] Required	The unique Id of the Family.

Table 11. Request Body
familyMember.userId [UUID] Required	The unique userId of the User to add to a family.
familyMember.owner [Boolean] Optional defaults to `false`	Set to `true` to indicate a family owner. This value will be ignored if the user role is `Teen` or `Child`.
familyMember.role [String] Required	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"
  }
}

4.2. Response

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

Table 12. 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.
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 updated 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.

Table 13. Response Body when retrieving a Family by Id
family.id [UUID]	The unique Id of the family.
family.members [Array<Object>]	The members of this family.
family.members`[x]`.insertInstant [Long]	The instant when the user was added to the family.
family.members`[x]`.owner [Boolean]	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]`.role [String]	The role of the family member. The possible values are: `Adult` `Child` `Teen`
family.members`[x]`.userId [UUID]	The unique user Id of the family member.

Example Response JSON

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

5. Remove a User from a Family

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

5.1. Request

Remove a User from a Family

URI

DELETE /api/user/family/{familyId}/{userId}

Table 14. Request Parameters
familyId [UUID] Required	The unique Id of the Family.
userId [UUID] Required	The unique Id of the User.

5.2. Response

This API does not return a JSON response body.

Table 15. 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.
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.

6. Retrieve Pending Family Members

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

6.1. Request

Retrieve pending users by parent email address

URI

GET /api/user/family/pending?parentEmail={parentEmail}

Table 16. Request Parameters
parentEmail [String] Required	The email address of the parent.

6.2. Response

The response for this API contains the requested pending users.

Table 17. 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.
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.

Table 18. Response Body
users`[x]`.active [Boolean]	True if the User is active. False if the User has been deactivated. Deactivated Users will not be able to login.
users`[x]`.birthDate [String]	The User’s birthdate formatted as `YYYY-MM-DD`
users`[x]`.data [Object]	An object that can hold any information about the User that should be persisted.
users`[x]`.email [String]	The User’s email address.
users`[x]`.fullName [String]	The User’s full name as a separate field that is not calculated from firstName and lastName.
users`[x]`.id [UUID]	The User’s unique Id.
users`[x]`.insertInstant [Long]	The instant when user was created.
users`[x]`.parentEmail [String]	The user’s parent’s email address.
users`[x]`.passwordChangeRequired [Boolean]	Indicates that the User’s password needs to be changed during their next login attempt.
users`[x]`.passwordLastUpdateInstant [Long]	The instant that the User last changed their password.
users`[x]`.preferredLanguages [Array<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]`.tenantId [UUID]	The Id of the Tenant that this User belongs to.
users`[x]`.timezone [String]	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]`.twoFactorDelivery [String]	The User’s preferred delivery for verification codes during a two factor login request. The possible values are: `None` `TextMessage`
users`[x]`.twoFactorEnabled [Boolean]	Determines if the User has two factor authentication enabled for their account or not.
users`[x]`.username [String]	The username of the User.
users`[x]`.usernameStatus [String]	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]`.verified [Boolean]	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
  } ]
}

7. Request Parental Approval

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

7.1. Request

Request parental approval

URI

POST /api/user/family/request

Table 19. Request Headers
X-FusionAuth-TenantId [String] Optional	The Header specifying the Id of the Tenant this request is scoped for. This Header is not required when the Authorization header is provided with a tenant-scoped API key. Refer to the Tenant overview for more detail on providing a Tenant Id on the request.
Authorization [String] Optional	The Authorization header specifying a tenant-scoped API key as a Bearer token. This Header is not required when the X-FusionAuth-TenantId header is provided. Refer to the Tenant overview for more detail on providing a Tenant Id on the request.

Table 20. Request Body
parentEmail [String] Required	The email address of the parent.

Example Request JSON

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

7.2. Response

This API does not return a JSON response body.

Table 21. 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.
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.