Edit a partner user

Overview

Change a user's details, role, or access scope.

Use this when responsibilities change.

You'll need the user_id and the changes.

The user is updated; access changes take effect on their next request. Every call replaces the user's name, title, deactivation date and account list with what you send, so send the current values for anything you're not changing (get them from Get one user).

Prerequisites

A Partner token. See Authentication.
The user's id, from List users.

Base URL

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

Endpoint

POST /api/v1/users/partner/edit

Authentication

Partner token

The user must be at the same partner as the user behind the token; otherwise 403 Permission denied.
Every id in account must be an account inside your partner's tree; otherwise 422.
Only an Owner or Admin User can edit users. You can't edit the Owner, or a user who ranks above you (Owner, then Admin User, then User, Brand Assigned and Location Assigned, then Basic User). Otherwise 403.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Notes
`user`	integer	Yes	The id of the user to edit.
`user_type`	string	Yes	The user's role: `admin`, `assign_brand` (only the accounts in `account`) or `basic`. `admin` removes every account assignment.
`first_name`	string	Yes	Up to 255 characters. Can't contain `<` or `>`.
`last_name`	string	No	Up to 255 characters. Can't contain `<` or `>`. Left out, it's cleared.
`title`	string	No	Job title. Up to 50 characters. Can't contain `<` or `>`. Left out, it's cleared.
`password`	string	No	A new password: 8 to 100 characters, with upper- and lower-case letters, a number and a symbol. No quotes, backslashes or spaces. Leave it out or empty to keep the current password. A new password signs the user out everywhere: their tokens are revoked, except the API key from the dashboard's API Keys page.
`account`	array of integers	Yes, when `user_type` is `assign_brand`, or `basic` with `assign_all_accounts: 0`	The accounts the user can access. Replaces the current list. 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	`0` or `1`. Not used when editing; the user's report subscriptions don't change.
`inactive_at`	string	No	Date and time to deactivate the user, as `YYYY-MM-DD HH:MM:SS`. A date that has already passed deactivates the user straight away and revokes all of their tokens, including the API key. Left out or `null`, any deactivation date is cleared.

Request payload

{
  "user": 12,
  "user_type": "assign_brand",
  "first_name": "Jane",
  "last_name": "Smith",
  "title": "Manager",
  "account": [
    5994
  ],
  "inactive_at": null
}

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`response`	string	`User information has been updated successfully`

Response payload

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

Examples

Success payload

See Response payload.

Error payload

403 Permission denied

The user isn't at your partner.

{
  "message": "Forbidden",
  "status": "error",
  "errors": "Permission denied."
}

403 Not allowed to manage this user

You're not an Owner or Admin User, or the user is the Owner or ranks above you.

{
  "message": "Forbidden",
  "status": "error",
  "errors": "You do not have permission to manage this user."
}

422 Required fields missing

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

422 User doesn't exist

{
  "message": "The selected user is invalid.",
  "errors": {
    "user": [
      "The selected user is invalid."
    ]
  }
}

Status	Meaning
`200`	The user was updated.
`401`	The token is missing, expired or invalid.
`403`	The user isn't at your partner, or you're not allowed to manage them (see Authentication).
`422`	A field is missing or invalid, the user doesn't exist, 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/edit" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"user": 12, "user_type": "assign_brand", "first_name": "Jane", "last_name": "Smith", "title": "Manager", "account": [5994], "inactive_at": null}'