Add a partner user

Overview

Add a person at your partner with a role and access to chosen accounts or locations.

Use this to onboard a team member.

You'll need their name, email, role, and access scope.

The user is created and emailed a set-password link. With send_default_reports: 1 they're also subscribed to the monthly activity report and the weekly review responses report.

Prerequisites

A Partner token. See Authentication.
To limit the user to some accounts: the account ids, from List accounts.

Base URL

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

Endpoint

POST /api/v1/users/partner/add

Authentication

Partner token

The new user is created at the partner of the user behind the token.
Only an Owner or Admin User can add users. Anyone else gets 403.
Every id in account must be an account inside your partner's tree; otherwise 422.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Notes
`user_type`	string	Yes	The user's role: `admin`, `assign_brand` (only the accounts in `account`) or `basic`.
`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.
`account`	array of integers	Yes, when `user_type` is `assign_brand`, or `basic` with `assign_all_accounts: 0`	The accounts the user can access. Each must be inside your tree.
`assign_all_accounts`	integer	Yes, when `user_type` is `basic`	`1`: all accounts. `0`: only the accounts in `account`.
`send_default_reports`	integer	No	`1` subscribes the user to the monthly activity report and the weekly review responses 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

{
  "user_type": "assign_brand",
  "first_name": "Jane",
  "last_name": "Smith",
  "title": "Manager",
  "email": "<user-email>",
  "password": "<your-password>",
  "account": [
    5994
  ],
  "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`

Response payload

{
  "data": {
    "status": "success",
    "response": "User has been created successfully"
  }
}

Examples

Success payload

See Response payload.

Error payload

403 Not allowed to add users

The user behind the token isn't an Owner or Admin User.

{
  "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 taken, weak password, no accounts

{
  "message": "The account field is required. (and 5 more errors)",
  "errors": {
    "account": [
      "The account field is required."
    ],
    "email": [
      "The email has already been taken."
    ],
    "password": [
      "The password field must be at least 8 characters.",
      "The password field format is invalid.",
      "The password field must contain at least one uppercase and one lowercase letter.",
      "The password field must contain at least one number."
    ]
  }
}

422 Account outside your tree

{
  "message": "The selected account.0 does not belong to your company hierarchy.",
  "errors": {
    "account.0": [
      "The selected account.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 user behind the token isn't an Owner or Admin User.
`422`	A field is missing or invalid, the email is taken, or an account is outside your tree.
`500`	Unexpected server error. Nothing was saved.

Example request

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