User Reassignments API

Reassign a user’s responsibilities to a new user or access reassignment details for a specified reassignment action.

The User Reassignment API functions the same as the User Reassignments UI option. When reassigning a user's responsibilities, the API ignores invalid responsibilities, or responsibilities that the user being reassigned from does not possess.

The base URL to access User Reassignments is: https://{your_instance_name}/api/user_reassignments

For more information, see these resources:

Actions

The User Reassignments API allows you to:


Verb	Path	Action	Description
GET	`/api/user_reassignments/:id`	Show	Access the status and reassignment summary for a specified User Reassignment request. Use this method to understand the reassignment status and summary of reassigned documents from a preceding POST call.
POST	`/api/user_reassignments`	Create	Submit a user reassignment request.
GET	`/api/user_reassignments/:user_reassignment_id/transactions`	Index	Get the details of user reassignment requests.

Elements

The following elements are available for the User Reassignments API:


Element	Description	Required Field?	Allowable Value	Api_In Field?	Api_Out Field?	Data Type
from-user	User to take responsibilities from.	Yes		Yes	Yes	User
to-user	User to assign responsibilities to.	Yes		Yes	Yes	User
deactivate-from-user-after-reassignment	When true, deactivates the `from-user` after responsibilities are reassigned.	No		Yes	Yes	boolean
notes	Notes and details related to this user reassignment.	No		Yes	Yes	string
requested-reassignments:	Requested reassignments to be completed. See section below for definitions.	No		Yes	Yes	JSON array. See below for format and descriptions
object-type	Object type being reassigned	No			Yes
object-id	Object ID being reassigned	No			Yes
change-type	Change type	No			Yes
status	Whether reassignment was changed or failed	No	Changed, Failed		Yes	string
message	Error message if reassignment failed	No			Yes	string
summary	Summary of reassignment results if processing completed	No			Yes	JSON array. See below for format and descriptions

Requested Reassignments

This field takes a JSON array in the following format:

"requested-reassignments": {
        "memberships-and-roles": {
            "add-user-groups": true,
            "replace-as-user-group-owner": true,
            "add-projects": true,
            "replace-as-project-owner": false,
            "add-categories": false,
            "replace-as-category-owner": false,
            "add-content-groups": false,
            "add-roles": true
        },
        "documents": {
            "replace-as-requisition-requester": false,
            "replace-as-invoice-requester": false,
            "replace-as-contract-owner": false
        },
        "approvals": {
            "replace-in-approvals": true,
            "replace-as-delegate": false,
            "replace-as-ultimate-approver": false,
            "replace-as-watcher": true
        },
        "platform": {
            "replace-as-manager": false,
            "replace-as-integration-contact": false,
            "replace-as-budget-owner": false,
            "replace-as-report-recipient": false
        }
    }

These fields are defined as follows. If the deactivate-from-user-after-reassignment element is set to false, at least one of these elements must be set to true when sending a POST request.

Note:

Depending on the configuration of your instance, the approvals element might be named approvals-receiving-invoice-requester-access-contract-reviews.

Element	Description	Required Field?	Data Type
add-user-groups	Add user groups (including approval groups) that “to” user does not have		boolean
replace-as-user-group-owner	Replace as user group owner		boolean
add-projects	Add as member to projects that “to” user does not have		boolean
replace-as-project-owner	Replace as project owner		boolean
add-categories	Add as member to categories that “to” user does not have		boolean
replace-as-category-owner	Replace as category owner		boolean
add-content-groups	Add content groups that “to” user does not have		boolean
add-roles	Add roles that “to” user does not have		boolean
replace-as-requisition-requester	Replace as requester in requisitions including ordered requisitions where the orders are not cancelled or fully closed.		boolean
replace-as-invoice-requester	Replace as requester in invoices		boolean
replace-as-contract-owner	Replace as contract owner		boolean
replace-in-approvals	Replace “from” user in configured approval chains, as current approver, and in any approval list where “from” user was manually added		boolean
replace-as-delegate	Replace as delegate		boolean
replace-as-ultimate-approver	Replace as ultimate approver		boolean
replace-as-watcher	Replace as watcher		boolean
replace-as-manager	Replace as manager		boolean
replace-as-integration-contact	Replace as integration contact		boolean
replace-as-budget-owner	Replace as budget owner		boolean
replace-as-report-recipient	Replace as recipient of scheduled report		boolean

Summary

This field takes a JSON array in the following format:

"summary": {
   "selected": 5,
   "changed": 4,
   "failed": 1
}

These fields are defined as follows.

Element	Description	Data Type
selected	Total count of reassignments	string
Changed	Number of successful reassingments	string
failed	Number of failed reassingments	string

Add a new user reassignment request

Endpoint

POST /api/user_reassignments

Example cURL request

curl --location 'https://<your-instance>.com/api/user_reassignments' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--header 'Cookie: _mkra_ctxt=9bf0fc146dee34067ce9df6a3b071159c58a1eef257da14d26bc05312e54d6d5--201' \
--data '{
   "from-user":{
      "login":"c79d511f-c0fc-43f1-a849-ec59bbac18da"
   }, "to-user":{
      "login":"6970e846-a197-44c9-8909-67b8b8809ec3"
   }, "deactivate-from-user-after-reassignment":false,
   "notes":"Note Example",
   "requested-reassignments": {
        "memberships-and-roles": {
            "add-user-groups": true,
            "replace-as-user-group-owner": true,
            "add-projects": true,
            "replace-as-project-owner": false,
            "add-categories": false,
            "replace-as-category-owner": false,
            "add-content-groups": false,
            "add-roles": true
        },
        "documents": {
            "replace-as-requisition-requester": false,
            "replace-as-invoice-requester": false,
            "replace-as-contract-owner": false
        },
        "approvals_receiving_invoice_requester_access_contract_reviews": {
            "replace-in-approvals": true,
            "replace-as-delegate": false,
            "replace-as-ultimate-approver": false,
            "replace-as-watcher": true
        },
        "platform": {
            "replace-as-manager": false,
            "replace-as-integration-contact": false,
            "replace-as-budget-owner": false,
            "replace-as-report-recipient": false
        }
    }
}'

Example response

{
    "id": 37,
    "created-at": "2025-03-26T15:12:58-04:00",
    "updated-at": "2025-03-26T15:12:58-04:00",
    "status": "new",
    "notes": "Note Example",
    "deactivate-from-user-after-reassignment": false,
    "requested-reassignments": {
        "memberships-and-roles": {
            "add-user-groups": true,
            "replace-as-user-group-owner": true,
            "add-projects": true,
            "replace-as-project-owner": false,
            "add-categories": false,
            "replace-as-category-owner": false,
            "add-content-groups": false,
            "add-roles": true
        },
        "documents": {
            "replace-as-requisition-requester": false,
            "replace-as-invoice-requester": false,
            "replace-as-contract-owner": false
        },
        "approvals-receiving-invoice-requester-access-contract-reviews": {
            "replace-in-approvals": true,
            "replace-as-delegate": false,
            "replace-as-ultimate-approver": false,
            "replace-as-watcher": true
        },
        "platform": {
            "replace-as-manager": false,
            "replace-as-integration-contact": false,
            "replace-as-budget-owner": false,
            "replace-as-report-recipient": false
        }
    },
    "summary": null,
    "from-user": {
        "id": 76,
        "login": "c79d511f-c0fc-43f1-a849-ec59bbac18da",
        "employee-number": null,
        "firstname": "User",
        "lastname": "test",
        "fullname": "User test",
        "email": "user@coupa.com",
        "salesforce-id": null,
        "avatar-thumb-url": null,
        "custom-fields": {
            "mp-html": "",
            "userbusinessunit": null,
            "ap-custom-field-": null
        }
    },
    "to-user": {
        "id": 93,
        "login": "6970e846-a197-44c9-8909-67b8b8809ec3",
        "employee-number": null,
        "firstname": "First",
        "lastname": "Last",
        "fullname": "First Last",
        "email": "name@coupa.com",
        "salesforce-id": null,
        "avatar-thumb-url": null,
        "custom-fields": {
            "mp-html": "",
            "userbusinessunit": null,
            "ap-custom-field-": null
        }
    },
    "created-by": {
        "id": 24200,
        "login": "mytest2",
        "employee-number": null,
        "firstname": "My2",
        "lastname": "Test2",
        "fullname": "My2 Test2",
        "email": "mytest2@gmail.com",
        "salesforce-id": null,
        "avatar-thumb-url": null,
        "custom-fields": {
            "mp-html": "",
            "userbusinessunit": null,
            "ap-custom-field-": null
        }
    },
    "updated-by": {
        "id": 24200,
        "login": "mytest2",
        "employee-number": null,
        "firstname": "My2",
        "lastname": "Test2",
        "fullname": "My2 Test2",
        "email": "mytest2@gmail.com",
        "salesforce-id": null,
        "avatar-thumb-url": null,
        "custom-fields": {
            "mp-html": "",
            "userbusinessunit": null,
            "ap-custom-field-": null
        }
    }
}

Get the status of a user reassignment request

Method

GET /api/user_reassignments/:id