Update a share

v1.0.0

Change the settings on an active share. Any changes made will affect all users that have access to the share.

When updating invitees, pass the recipients body paramater with the full list of people who should be included on the share. If you resend the list without an existing recipient, they will be removed from the share.

Setting the Share Permissions

Only 5 different combinations of permissions are valid for the accessMode object:

Upload Only: This allows share visitors to upload to a share but do nothing else to the contained files. To use this mode, set upload to true and all other permissions to false
Download Only: This allows share visitors to download files from a share but do nothing else to the contained files. To use this mode, set download to true and all other permissions to false
Upload and Download: This allows share visitors to upload new files to the share or download files within the share, but not make any other changes to the share contents. To use this mode, set upload and download to true and set both modify and delete to false
All but Delete: This allows share visitors to make any changes to the contents of a share except deleting files. To use this mode, set upload, download, and modify to true and set delete to false
Full Access: This allows share visitors to make any changes to the contents of a share. To use this mode, set all 4 permissions upload, download, modify, and delete to true

Any other combination of permissions provided as the accessMode will be rejected as a bad request.

Notes:

Authenticated user should be the owner of the specified share.

Input

{
  "type": "object",
  "properties": {
    "accessMode": {
      "type": "object",
      "description": "An object defining what a not-logged-in visitor can do with the share contents",
      "properties": {
        "delete": {
          "type": "boolean",
          "description": "Whether share allows visitors to delete contents"
        },
        "download": {
          "type": "boolean",
          "description": "Whether share allows visitors to download"
        },
        "modify": {
          "type": "boolean",
          "description": "Whether share allows visitors to rename or move contents."
        },
        "upload": {
          "type": "boolean",
          "description": "Whether share allows visitors to upload"
        }
      }
    },
    "embed": {
      "type": "boolean",
      "description": "Whether the share can be embedded in another web page."
    },
    "ev-access-token": {
      "type": "string"
    },
    "ev-api-key": {
      "type": "string"
    },
    "expiration": {
      "type": "string",
      "format": "date-time",
      "description": "New expiration date and time for the share"
    },
    "fileDropCreateFolders": {
      "type": "boolean",
      "description": "Whether uploads to a receive folder should be automatically placed into subfolders. See our [receive folder documentation](/docs/account/05-file-sharing/05-form-builder#advanced-form-settings)"
    },
    "hasNotification": {
      "type": "boolean",
      "description": "Whether delivery receipts should be sent for this share."
    },
    "isPublic": {
      "type": "boolean",
      "description": "Whether people can visit the share without following a link from an invitation email"
    },
    "messageBody": {
      "type": "string",
      "description": "Message content to use for emails inviting recipients to the share. Ignored if you have not also provided `recipients` and a `subject`"
    },
    "messageSubject": {
      "type": "string",
      "description": "Subject to use on emails inviting recipients to the share. Ignored if you have not also provided `recipients` and a `message`"
    },
    "name": {
      "type": "string",
      "description": "Name of the share."
    },
    "notificationEmails": {
      "type": "array",
      "description": "List of email addresses to send delivery receipts to. Ignored if `hasNotification` is false. ",
      "items": {
        "type": "string",
        "format": "email"
      }
    },
    "password": {
      "type": "string",
      "description": "New password for the share. To leave the password unchanged, do not send this parameter."
    },
    "recipients": {
      "type": "array",
      "description": "People you want to invite to the share. \n\n**Note**: unless you also set the `subject` and `message` for the new share, invitation emails will not be sent to these recipients.\n\n**Note**: Recipients in this list will **REPLACE** the recipients already assigned to this share. ",
      "items": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address of person you are inviting to the share"
          },
          "type": {
            "type": "string",
            "description": "What kind of email should be sent to this recipient. Valid choices are **direct** and **cc**"
          }
        }
      }
    },
    "requireEmail": {
      "type": "boolean",
      "description": "Whether visitors to the share will be required to enter their email in order to access the share."
    },
    "resources": {
      "type": "array",
      "description": "Array of resources for this share. See details on [how to specify resources](#section/Identifying-Resources) above.\n\n**shared_folder** and **receive** shares must have only one `resource`, which is a directory that does not have a current share attached.\n\n**send** shares may have multiple `resource` parameters. \n\n**NOTE**: Sending this parameter will **REPLACE** the existing resources with the resources included in this request.",
      "items": {
        "type": "string"
      }
    },
    "status": {
      "type": "integer",
      "description": "New status for the share. You can set an active share to inactive by setting the status to **0**"
    }
  },
  "required": [
    "ev-access-token",
    "ev-api-key"
  ],
  "additionalProperties": false
}

Output

{
  "type": "object",
  "description": "Response object for shares.",
  "properties": {
    "data": {
      "type": "object",
      "description": "Object contains share properties.",
      "properties": {
        "attributes": {
          "type": "object",
          "description": "Attributes of the share including the name, path and share recipients. ",
          "properties": {
            "accessDescription": {
              "type": "string",
              "description": "Description of the share access rights."
            },
            "accessMode": {
              "type": "object",
              "description": "An object defining what a not-logged-in visitor can do with the share contents",
              "properties": {
                "delete": {
                  "type": "boolean",
                  "description": "Whether share allows visitors to delete contents"
                },
                "download": {
                  "type": "boolean",
                  "description": "Whether share allows visitors to download"
                },
                "modify": {
                  "type": "boolean",
                  "description": "Whether share allows visitors to rename or move contents."
                },
                "upload": {
                  "type": "boolean",
                  "description": "Whether share allows visitors to upload"
                }
              }
            },
            "created": {
              "type": "string",
              "format": "date-time",
              "description": "Timestamp of share creation."
            },
            "embed": {
              "type": "boolean",
              "description": "True if share can be embedded."
            },
            "expiration": {
              "type": "string",
              "description": "Expiration date of the share."
            },
            "expired": {
              "type": "boolean",
              "description": "True if the share has expired.",
              "enum": [
                true,
                false
              ]
            },
            "fileDropCreateFolders": {
              "type": "boolean",
              "description": "Flag to show if separate folders should be created for each file upload to receive folder.",
              "enum": [
                true,
                false
              ]
            },
            "formId": {
              "type": "integer",
              "description": "ID of the form."
            },
            "hasNotification": {
              "type": "boolean",
              "description": "True if share has notification.",
              "enum": [
                true,
                false
              ]
            },
            "hasPassword": {
              "type": "boolean",
              "description": "True if the share has password.",
              "enum": [
                true,
                false
              ]
            },
            "hash": {
              "type": "string",
              "description": "Share hash."
            },
            "inherited": {
              "type": "boolean",
              "description": "True if share inherited from parent folder.",
              "enum": [
                true,
                false
              ]
            },
            "messages": {
              "type": "array",
              "description": "Array of invitation messages.",
              "items": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "description": "Share invitation message text."
                  },
                  "created": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Timestamp of message creation."
                  },
                  "id": {
                    "type": "integer",
                    "format": "int32",
                    "description": "Message id."
                  },
                  "modified": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Timestamp of message modification."
                  },
                  "shareId": {
                    "type": "integer",
                    "format": "int32",
                    "description": "ID of associated share"
                  },
                  "subject": {
                    "type": "string",
                    "description": "Share invitation message subject."
                  },
                  "userId": {
                    "type": "integer",
                    "format": "int32",
                    "description": "User ID who generated share invite"
                  }
                }
              }
            },
            "modified": {
              "type": "string",
              "format": "date-time",
              "description": "Timestamp of share modification. Can be `null` if it wasn't modified."
            },
            "name": {
              "type": "string",
              "description": "Share name."
            },
            "ownerHash": {
              "type": "string",
              "description": "Share owner's hash."
            },
            "paths": {
              "type": "array",
              "description": "Path to the shared resource in your account.",
              "items": {
                "type": "string"
              }
            },
            "public": {
              "type": "boolean",
              "description": "True if the share has a public url.",
              "enum": [
                true,
                false
              ]
            },
            "recipients": {
              "type": "array",
              "description": "Array of recipients.",
              "items": {
                "type": "object",
                "properties": {
                  "created": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Timestamp of adding recipient to the share."
                  },
                  "email": {
                    "type": "string",
                    "description": "Recipient email address."
                  },
                  "hash": {
                    "type": "string",
                    "description": "Share hash."
                  },
                  "id": {
                    "type": "integer",
                    "format": "int32",
                    "description": "ID of the recipient."
                  },
                  "received": {
                    "type": "boolean",
                    "description": "Set to true if recipient has accessed the share. Note this is set to true when the recipient clicks the link to access the share; not when they download a file.",
                    "enum": [
                      true,
                      false
                    ]
                  },
                  "sent": {
                    "type": "boolean",
                    "description": "Set to true if invite email was sent; false otherwise.",
                    "enum": [
                      true,
                      false
                    ]
                  },
                  "shareId": {
                    "type": "string",
                    "description": "ID of the share that the recipoient belongs to."
                  },
                  "type": {
                    "type": "string",
                    "description": "Type of the recipient.",
                    "enum": [
                      "owner",
                      "direct"
                    ]
                  }
                }
              }
            },
            "requireEmail": {
              "type": "boolean",
              "description": "True if share requires email to access."
            },
            "resent": {
              "type": "string",
              "format": "date-time",
              "description": "Invitations resent date. Can be `null` if resent never happened."
            },
            "status": {
              "type": "integer",
              "format": "int32",
              "description": "Share activity status. Can be active (1) or deactivated (0).",
              "enum": [
                0,
                1
              ]
            },
            "trackingStatus": {
              "type": "string",
              "description": "Checks recipient received status and returns whether it's been received (`complete`,) partial received (`incomplete`,) or not received yet (`pending`.)",
              "enum": [
                "complete",
                "incomplete",
                "pending"
              ]
            },
            "type": {
              "type": "string",
              "description": "Type of share.",
              "enum": [
                "shared_folder",
                "send",
                "receive"
              ]
            }
          }
        },
        "id": {
          "type": "integer",
          "format": "int32",
          "description": "ID of the share."
        },
        "relationships": {
          "type": "object",
          "description": "Message, owner, resource, and notification relationships of the share. ",
          "properties": {
            "messages": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "data": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "description": "ID of the message."
                      },
                      "type": {
                        "type": "string",
                        "description": "Type is message. ",
                        "enum": [
                          "message"
                        ]
                      }
                    }
                  }
                }
              }
            },
            "notifications": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "data": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "description": "ID of the notification. "
                      },
                      "type": {
                        "type": "string",
                        "description": "Type is notification. ",
                        "enum": [
                          "notification"
                        ]
                      }
                    }
                  }
                }
              }
            },
            "owner": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "description": "ID of the owner."
                    },
                    "type": {
                      "type": "string",
                      "description": "Type is user."
                    }
                  }
                }
              }
            },
            "resources": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "data": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "format": "int64",
                        "description": "ID of the shared resource."
                      },
                      "type": {
                        "type": "string",
                        "description": "Type is resource. ",
                        "enum": [
                          "resource"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "type": {
          "type": "string",
          "description": "Type of the share. ",
          "enum": [
            "share"
          ]
        }
      }
    },
    "included": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "responseStatus": {
      "type": "integer",
      "description": "Http status code of the response."
    }
  }
}