Patch User #

Updates a specific set of properties of a User. This uses the JSON Patch format for any changes.

PATCH /v1.0/accounts/{ACCOUNT_TENANT_ID}/customers/{CUSTOMER_TENANT_ID}/users/{USER_ID}

warning
When patching the roles against a user, be careful if using the REPLACE operation. With the replace operation, the user's current roles will be replaced with the values provided in the patch request. Any role not provided in the patch request will be removed from the user (with the exception of the PBX user role which is synchronized from the PBX).

Example 1 #

This request will update the Display Name of the User.

Request #

PATCH https://api.na.myreports.cloud/api/v1.0/accounts/{ACCOUNT_TENANT_ID}/customers/{CUSTOMER_TENANT_ID}/users/{USER_ID} HTTP/1.1
Content-Type: application/json
accept-charges: true
Authorization: Bearer {TOKEN}
Connection: keep-alive
[{
	"op": "replace",
	"path": "/displayName",
	"value": "My New Name"
}]

Response #

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: xx
Request-Context: appId=cid-v1:d24f4c80-0a0a-432e-85aa-a6f91f13a038
{
	"status": "success",
	"timestamp": "2019-11-29T15:16:54.2586208Z"
}

Example 2 #

This request will ADD the customer.user.supervisorl1 role to the User, keeping existing roles intact.

Request #

PATCH https://api.na.myreports.cloud/api/v1.0/accounts/{ACCOUNT_TENANT_ID}/customers/{TENANT_ID}/users/{USER_ID} HTTP/1.1
Content-Type: application/json
accept-charges: true
Authorization: Bearer {TOKEN}
Connection: keep-alive
[{
	"op": "add",
	"path": "/roles/-",
	"value": "customer.user.supervisorl1"
}]

Response #

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: xx
Request-Context: appId=cid-v1:d24f4c80-0a0a-432e-85aa-a6f91f13a038
{
	"status": "success",
	"timestamp": "2019-11-29T15:16:54.2586208Z"
}

Example 3 #

This request will replace ALL roles assigned to the User with the two provided.

Request #

PATCH https://api.na.myreports.cloud/api/v1.0/accounts/{ACCOUNT_TENANT_ID}/customers/{TENANT_ID}/users/{USER_ID} HTTP/1.1
Content-Type: application/json
accept-charges: true
Authorization: Bearer {TOKEN}
Connection: keep-alive
[{
	"op": "replace",
	"path": "/roles",
	"value": ["user.admin", "customer.user"]
}]

Response #

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: xx
Request-Context: appId=cid-v1:d24f4c80-0a0a-432e-85aa-a6f91f13a038
{
	"status": "success",
	"timestamp": "2019-11-29T15:16:54.2586208Z"
}

Errors #

Unauthorized #

When the token is not provided, invalid or expired

HTTP/1.1 401 Unauthorized

Bad Request (1) #

When the provided tenant or user id is not in the correct format

HTTP/1.1 400 Bad Request
Date: Thu, 06 Feb 2020 12:45:27 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 149
{
	"error": 400,
	"message": "The value '<tenant/user id>' is not valid.",
	"status": "error",
	"timestamp": "2020-02-06T12:45:27.5903465Z"
}

Bad Request (2) #

When the last User with the "user.admin" and "customer.user" role in this Customer tries to have this role removed.

warning
There always needs to be a User in a Customer tenant with both the "user.admin" and "customer.user" roles.

HTTP/1.1 400 Bad Request
Date: Thu, 06 Feb 2020 13:12:06 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 132
{
	"error": 400,
	"message": "There must be at least one user administrator.",
	"status": "error",
	"timestamp": "2020-02-06T13:12:06.9741515Z"
}

Bad Request (3) #

When attempting to patch an invalid property.

HTTP/1.1 400 Bad Request
Date: Thu, 06 Feb 2020 12:45:27 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 149
{
	"error": 400,
	"message": "The target location specified by path segment '<invalid property>' was not found.",
	"status": "error",
	"timestamp": "2020-02-06T12:45:27.5903465Z"
}

Conflict #

If the email address for this new user already exits for another user in this Customer tenant

HTTP/1.1 409 Conflict
Date: Thu, 06 Feb 2020 13:05:39 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 178
{
	"error": 409,
	"errorCode": "EmailConflict",
	"message": "A user with the email address [email protected] already exists.",
	"status": "error",
	"timestamp": "2020-02-06T13:05:39.5486342Z"
}

Not Found #

When there are no Customers that have a matching tenant id, or Users within this tenant that have a matching user id

HTTP/1.1 404 Not Found
Date: Thu, 06 Feb 2020 12:46:58 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 95
{
	"error": 404,
	"message": "Not Found",
	"status": "error",
	"timestamp": "2020-02-06T12:46:58.7669535Z"
}

Payment Required #

If this request may incur any additional charges, see Charges.

HTTP/1.1 402 Payment Required
Date: Thu, 06 Feb 2020 13:01:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 274
{
	"data": {
		"id": "{USER_ID}",
		"displayName": "New User",
		"email": "[email protected]",
		"primaryTenant": "{CUSTOMER_TENANT_ID}",
		"roles": ["admin.user", "customer.user", "customer.user.supervisorl1", "customer.settings"]
	},
	"error": 402,
	"message": "additional charges apply",
	"status": "error",
	"timestamp": "2020-02-06T13:01:01.1302340Z"
}