Skip to content
ShareOutShareOut Docs

Share a file or folder with one person by email

POST
/v1/workspaces/{workspaceId}/share-person
curl --request POST \
  --url https://shareout.site/v1/workspaces/example/share-person \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "email": "hello@example.com", "resource_type": "file", "resource_id": "example", "capability": "view", "expires_in_days": 1, "expires_at": "example", "guest": false }'

Admin, or the folder’s manager for a folder. Only the role is relaxed for a manager: every share needs the external-sharing entitlement (Teams/Enterprise, or the collab.external_sharing feature on self-host; 403 EXTERNAL_SHARING_NOT_ENTITLED) and an email the workspace’s allowed domains or emails accept (403 DOMAIN_NOT_ALLOWED). Invites an external user if needed and mints an external_user grant; re-sharing is idempotent and replaces the expiry. For a folder, the invite email’s join link carries ?folder=<id> through sign-in and lands on /shared?folder=<id> (that folder’s branded portal); an already-active person’s email links there too. Returns 409 if the email is already an internal member. With guest: true (folders only) no account is created: a guest grant whose subject is the email itself, and an emailed link that opens the folder in a space-guest session. The guest can also open it from /shared?folder=<id> with an email code. They see that folder’s subtree only, up to the capability; revoking or expiring the grant ends their session on the next request.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
workspaceId
required
string

Workspace ID or slug.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
email
required
string format: email
resource_type
required
string
Allowed values: file folder
resource_id
required
string
capability
string
default: view
Allowed values: view comment
expires_in_days

Access ends this many days from now (UI presets 7/30/90). Wins over expires_at.

integer
>= 1 <= 3650
expires_at

ISO date-time (or YYYY-MM-DD = end of that day, UTC) when access ends. Omit both for no expiry; a re-share replaces the previous expiry.

string
guest

Folders only. Share as a guest with no account (subject_type guest); the person gets an emailed link instead of an invite.

boolean

Responses

Section titled “Responses”

201

Section titled “201”

Grant created (idempotent re-share)

Media typeapplication/json
object
grant
object
id
string
subject_type
string
Allowed values: sharee external_user guest
subject_id

Sharee id, users.id, or for a guest grant the guest’s email.

string
resource_type
string
Allowed values: folder artifact file
resource_id
string
capability
string
Allowed values: view comment create edit
granted_by
string
created_at
string format: date-time
expires_at

When access ends (share-with-a-person expiry); null = never. A lapsed grant is denied at read time.

string | null format: date-time
subject_label

The person’s email or the client’s name (list endpoint).

string
email
string
guest

Present and true for a guest share.

boolean
email_sent

Guest shares only — whether the link email went out.

boolean
Example
{
  "grant": {
    "subject_type": "sharee",
    "resource_type": "folder",
    "capability": "view"
  }
}

400

Section titled “400”

VALIDATION_ERROR — bad email, resource, capability or expiry

403

Section titled “403”

Access denied

Media typeapplication/json
object
success
required
boolean
error
required

Human-readable message.

string
code
required

Machine-readable error code.

string
request_id

Correlation id (also the X-Request-Id header). Quote it in support tickets.

string
reason

Finer cause under code. For UNAUTHORIZED: missing, invalid, revoked or expired.

string
hint

What to do next, in plain words.

string
suggestion
string
param

The request field at fault.

string
docs

Doc page for this error.

string
redirect_url
string
support

Present on 5xx — how to reach a human.

object
how
string
include
Array<string>
Example
{
  "success": false,
  "support": {
    "how": "POST /v1/support/tickets",
    "include": [
      "request_id"
    ]
  }
}

409

Section titled “409”

Email is already an internal workspace member