Content Ownership Transfer API Examples

The following use case examples demonstrate how to perform two tasks:

📘

How to use these examples

  • Each use case below contains an API example using cURL. Visit the API Reference to test the API using other languages.
  • You’ll need a valid API key to test these examples and generate a response.

Example: Create job

The POST endpoint creates a transfer job. The following rules apply to the transfer job:

  • The job runs in the background.

  • The job applies to all content belonging to the transferFromUser across all workspaces.

  • The job transfers content ownership from the transferFromUser to the transferToUser.

URL

https://api.mural.co/enterprise/v1/workspaces/contents/transfer

Request body

A JSON request body matching the following schema is required:

  • transferFromUser: The email address of the "from" member (source).

  • transferToUser: The email of the "to" member (destination).

{
   "transferFromUser": "[email protected]",
   "transferToUser": "[email protected]"
}

Example request

curl --request POST \
--url https://api.mural.co/enterprise/v1/workspaces/contents/transfer \
--header 'Authorization: apiKey ABCDEFGHIJKLMNOPQRSTUVWXYZ \
--header 'Content-Type: application/json' \
--data-raw '{
   "transferFromUser": "[email protected]",
   "transferToUser": "[email protected]"
}'

Example response

A successful request returns a 200 response with a corresponding jobId. The jobId can then be used to query the status of the job using the GET endpoint.

{
   "jobId": "00270a08ed58-3e89-2a74-0007-e14a0785"
}

In case of errors, the request will return a 400-range status code with details. For example:

{
   "error": "SAME_USER"
}

Error codes

Possible errors are detailed below:

Status CodeErrorDescription
401API_KEYThe API key was not included in the request header.
403SCOPESThe API key does not have the manage_content scope.
400SAME_USERThe "from" and "to" members are the same.
400FROM_USER_NOT_MEMBERThe "from" member is not a member of the company.
400TO_USER_NOT_MEMBERThe "to" member is not a member of the company.
429N/AYour app has exceeded the rate limit for the API, a maximum of 25 per second.

Example: Get job status

This GET endpoint gets the status of an existing job.

URL

https://api.mural.co/enterprise/v1/workspaces/contents/transfer/:jobId

Example request

curl --location --request GET https://api.mural.co/enterprise/v1/workspaces/contents/transfer/0020a41e-7000-47a2-98e3-85de80a07785 \
--header 'Authorization: apiKey ABCDEFGHIJKLMNOPQRSTUVWXYZ' \

Example response

A successful request will return a 200 response with the job status.

{
   "status": "in-progress"
}

Status details

Possible status outcomes are detailed below:

Job StatusDescription
in-progressThe transfer operation is in progress. Some content may have already been moved.
finishedThe transfer operation completed successfully.

Ownership of all content from the transferFrom member has been moved to the transferTo member.
failedThe transfer operation did not complete successfully. See additional error details.

Errors

Possible errors are detailed below:

Status CodeErrorDescription
401API_KEYThe API key was not included in the request header.
403SCOPESThe API key does not have the manage_content scope.
400SAME_USERThe "from" and "to" members are the same.
400FROM_USER_NOT_MEMBERThe "from" member is not a member of the company.
400TO_USER_NOT_MEMBERThe "to" member is not a member of the company.
429N/AYour app has exceeded the rate limit for the API, a maximum of 25 per second.

Failed transfers

If the job fails to complete, an additional error will be returned, along with workspaceIds when applicable.

{
   "status": "failed",
   "error": "TO_USER_NOT_WORKSPACE_MEMBER",
   "workspaceIds": ["workspace123"]
}

Possible errors for a failed transfer are detailed below:

ErrorDescription
TO_USER_NOT_WORKSPACE_MEMBERThe transferTo user is not a member of one or more workspaces of the transferFrom user.

No content has been transferred.

Additional information

See these other articles for more information:


Did this page help you?