# Create a link a named person can open, so an agent can hand its work to an… `POST /share-links` **Required scope:** `documents:read` Create a link a named person can open, so an agent can hand its work to an investor or adviser. Recipients are required, because a link without them cannot be opened and naming them is what makes access attributable. An expiry is required too: permanent access to a customer's documents is not something an agent should be able to create by omission. ## Request body Content type: `application/json` (required) | Field | Type | Required | Description | |---|---|---|---| | `resourceType` | string | **yes** | document \| folder \| workspace (required) | | `resourceId` | string | **yes** | the id of the thing to share (required) | | `recipientEmails` | string | **yes** | array of the people who may open it (required, at least one) | | `expiresInDays` | string | **yes** | 1 to 365 (required). A link an agent creates must expire | | `accessLevel` | string | no | view \| download (default view) | ## Responses | Status | Meaning | |---|---| | `201` | Created. `url` is the link to send. Returns: id, url, resourceType, resourceId, accessLevel, recipientEmails, expiresAt. Each recipient confirms a code sent to their email before the link opens, and access is logged per email address rather than per device. | | `400` | BadRequest | | `401` | Unauthorized | | `403` | Forbidden | | `429` | RateLimited | ## Example ```bash curl -X POST "https://backend.immut.io/api/v1/share-links" \ -H "Authorization: Bearer $IMMUT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"resourceType":"","resourceId":"","recipientEmails":"","expiresInDays":"","accessLevel":""}' ``` ## OpenAPI fragment ```json { "/share-links": { "post": { "operationId": "postsharelinks", "summary": "Create a link a named person can open, so an agent can hand its work to an investor or adviser. Recipients are required, because a link without them cannot be opened and naming them is what makes access attributable. An expiry is required too: permanent access to a customer's documents is not something an agent should be able to create by omission.", "description": "Create a link a named person can open, so an agent can hand its work to an investor or adviser. Recipients are required, because a link without them cannot be opened and naming them is what makes access attributable. An expiry is required too: permanent access to a customer's documents is not something an agent should be able to create by omission.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resourceType": { "type": "string", "description": "document | folder | workspace (required)" }, "resourceId": { "type": "string", "description": "the id of the thing to share (required)" }, "recipientEmails": { "type": "string", "description": "array of the people who may open it (required, at least one)" }, "expiresInDays": { "type": "string", "description": "1 to 365 (required). A link an agent creates must expire" }, "accessLevel": { "type": "string", "description": "view | download (default view)" } }, "required": [ "resourceType", "resourceId", "recipientEmails", "expiresInDays" ] } } } }, "responses": { "201": { "description": "Created. `url` is the link to send. Returns: id, url, resourceType, resourceId, accessLevel, recipientEmails, expiresAt. Each recipient confirms a code sent to their email before the link opens, and access is logged per email address rather than per device." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "documents:read" } } } ```