Add an account user

Overview

Add a person at a business with access to chosen locations.

Use this to give a manager or staff member a login.

You'll need their name, email, role, and locations.

The user is created and emailed a set-password link. With send_default_reports: 1 they're also subscribed to the monthly activity report, the weekly review responses report and the monthly insight report; the response lists which reports were turned on.

Prerequisites

An Account token. See Authentication.
To limit the user to some locations: the location ids (store_ids).

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/user/add

Authentication

Account token

The new user is created at the account of the user behind the token.
Only an Owner or Admin User of the account can add users. Anyone else, or any other token (for example a Partner token), gets 403.
Every id in store_ids must be a location inside your account; otherwise 422.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Notes
`first_name`	string	Yes	Up to 255 characters. Can't contain `<` or `>`.
`last_name`	string	No	Up to 255 characters. Can't contain `<` or `>`.
`title`	string	No	Job title. Up to 50 characters. Can't contain `<` or `>`.
`email`	string	Yes	A valid email address, not already used by another user. The domain must accept mail (it's checked with a DNS lookup), so test domains like `example.com` are rejected with `422`.
`password`	string	Yes	8 to 100 characters, with upper- and lower-case letters, a number and a symbol. No quotes, backslashes or spaces.
`user_type`	string	Yes	The user's role: `admin`, `location_assign` (only the locations in `store_ids`) or `basic`.
`store_ids`	array of integers	Yes, when `user_type` is `location_assign`, or `basic` with `assign_all_accounts: 0`	The locations the user can access. Each must be inside your account.
`assign_all_accounts`	integer	Yes, when `user_type` is `basic`	`1`: all locations. `0`: only the locations in `store_ids`.
`send_default_reports`	integer	No	`1` subscribes the user to the monthly activity report, the weekly review responses report and the monthly insight report. `0` or left out: no reports.
`inactive_at`	string	No	Date and time to deactivate the user, as `YYYY-MM-DD HH:MM:SS`. Leave it out or send `null` for no deactivation date.

Request payload

{
  "first_name": "Jane",
  "last_name": "Smith",
  "title": "Manager",
  "email": "<user-email>",
  "password": "<your-password>",
  "user_type": "location_assign",
  "store_ids": [
    3007
  ],
  "send_default_reports": 1,
  "inactive_at": null
}

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`response`	string	`User has been created successfully`
`error`	array of strings	Default reports that couldn't be turned on. Empty unless `send_default_reports` is `1`.
`info`	array of strings	Default reports the email address already receives, so they were left as they are.
`success`	array of strings	Default reports that were turned on.

Response payload

{
  "data": {
    "status": "success",
    "response": "User has been created successfully",
    "error": [],
    "info": [],
    "success": [
      "Activity Report has been enabled.",
      "Review Response Report has been enabled.",
      "Insight Report has been enabled."
    ]
  }
}

Examples

Success payload

Without send_default_reports:

{
  "data": {
    "status": "success",
    "response": "User has been created successfully",
    "error": [],
    "info": [],
    "success": []
  }
}

Error payload

403 Not allowed to add users

{
  "message": "This action is unauthorized."
}

422 Required fields missing

{
  "message": "The user type field is required. (and 3 more errors)",
  "errors": {
    "user_type": [
      "The user type field is required."
    ],
    "first_name": [
      "The first name field is required."
    ],
    "email": [
      "The email field is required."
    ],
    "password": [
      "The password field is required."
    ]
  }
}

422 Email rejected, location outside your account

{
  "message": "The email field must be a valid email address. (and 1 more error)",
  "errors": {
    "email": [
      "The email field must be a valid email address."
    ],
    "store_ids.0": [
      "The selected store_ids.0 does not belong to your company hierarchy."
    ]
  }
}

Status	Meaning
`200`	The user was created.
`401`	The token is missing, expired or invalid.
`403`	The token isn't an Account token, or its user isn't an Owner or Admin User.
`422`	A field is missing or invalid, the email is taken or rejected, or a location is outside your account.
`500`	Unexpected server error. Nothing was saved.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/user/add" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"first_name": "Jane", "last_name": "Smith", "title": "Manager", "email": "<user-email>", "password": "<your-password>", "user_type": "location_assign", "store_ids": [3007], "send_default_reports": 1, "inactive_at": null}'