Add a home member

POST/homes/{homeId}/members

Base URL: https://api.tinkermode.com

Description

Add a member to the home. Only existing home members with the OWNER role may make this request. Based on the type of the project, this API call does one of the following:

Project Uses the Built-In Account System (Based on Email Addresses)

Add a member to the home. The member's email address must be specified. If the member is not an existing user, the "verified" field of the returned member object will be false. An email notification will be sent to the invited member.

Project Uses the Built-In Account System (Based on Phone Numbers)

Add a member to the home. The member's phone number must be specified. If the member is not an existing user, the "verified" field of the returned member object will be false. It is the app's responsibility to send an SMS invite to the invited member.

Project is BYOU ("Bring-Your-Own-Users")

Add an existing user with the specified user ID to a home.

Authentication

Send an Authorization header of the form ModeCloud <AUTH_CODE>.

Must contain user API key of the home owner, a service account token with manage-permissions on the home, or Project API key with "Admin" privileges.

Path parameters

NameTypeRequiredConstraintsDescription
homeIdintegerYesThe unique ID for a specified home.

Request body

Content type: application/x-www-form-urlencoded

PropertyTypeRequiredConstraintsDescription
emailstringNoMember's email address. Required for projects with email address-based user accounts.
phoneNumberstringNoMember's phone number. Required for projects with phone number-based user accounts.
rolestringNoOptional field to set the role of the new member. By default, new members are given the OWNER role.
silentbooleanNoOptional field to suppress email notification to the new member. Applicable only to email address-based user accounts.
userIdintegerNoA valid user ID. Required for BYOU projects.

Request example

phoneNumber=%2B17149999999

Responses

201 Successfully added a new home member.

Content type: application/json

PropertyTypeRequiredConstraintsDescription
creationTimestringNoread-only (server-generated); format: date-timeTimestamp when member was added to home.
emailstringNoread-only (server-generated)Email address of member.
namestringNoread-only (server-generated)Display name of member.
phoneNumberstringNoread-only (server-generated); pattern: ^(\+)([0-9]{5,})$Phone number used by member. Must begin with country code (beginning with the '+' symbol).
roleunknownNoone of: owner, memberIf the role is OWNER, this member can add or remove other members.
userIdintegerYesread-only (server-generated)User ID of home member.
verifiedbooleanYesread-only (server-generated)True if member is a verified user.

Response example

{
  "creationTime": "2019-12-18T20:12:13.478Z",
  "phoneNumber": "+17149999999",
  "role": "owner",
  "userId": 2083,
  "verified": false
}

401 Authorization is required to access this resource.

Content type: application/json

PropertyTypeRequiredConstraintsDescription
dataobjectNoread-only (server-generated)Any relevant data related to error.
reasonstringYesread-only (server-generated)Reason of error.

403 Request failed because of invalid data or denied permission.

Content type: application/json

PropertyTypeRequiredConstraintsDescription
dataobjectNoread-only (server-generated)Any relevant data related to error.
reasonstringYesread-only (server-generated)Reason of error.

429 Request failed because of rate limit.

Content type: application/json

PropertyTypeRequiredConstraintsDescription
dataobjectNoread-only (server-generated)Any relevant data related to error.
reasonstringYesread-only (server-generated)Reason of error.

500 An unexpected error has occurred.

Content type: application/json

PropertyTypeRequiredConstraintsDescription
dataobjectNoread-only (server-generated)Any relevant data related to error.
reasonstringYesread-only (server-generated)Reason of error.

503 The service is temporarily unavailable.

Content type: application/json

PropertyTypeRequiredConstraintsDescription
dataobjectNoread-only (server-generated)Any relevant data related to error.
reasonstringYesread-only (server-generated)Reason of error.