const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
recipients: [
{
role: 'viewer',
user_id: 'usr_01h2xcejqtf2nbrexx3vqjhp41',
email: 'alice@example.com',
bot_id: 'bot_01h2xcejqtf2nbrexx3vqjhp41'
}
],
should_send_notification: true,
custom_message: '<string>'
})
};
fetch('https://api.factify.com/v1/documents/{document_id}/sharing', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"total": 2,
"successful": 1,
"failed": 1,
"results": [
{
"recipient": {
"role": "viewer",
"user_id": "usr_01h2xcejqtf2nbrexx3vqjhp41",
"email": "alice@example.com",
"bot_id": "bot_01h2xcejqtf2nbrexx3vqjhp41"
},
"success": true,
"error": "<string>"
}
]
}Grant access to a document
Grants one or more recipients access to a document. Each recipient
is one of {user_id, email, bot_id} + role. Email recipients
that don’t yet resolve to a user trigger a placeholder user row
which gets linked to a Cognito identity on first sign-in.
Returns 200 with per-recipient {success, error} results — partial
failures (e.g. role-ceiling rejection, recipient already has
access) are surfaced per row rather than failing the whole batch.
Role-ceiling: the caller’s own role bounds what they can grant. A caller may grant any role at or below their own (e.g. a commenter can grant commenter or viewer); only the document owner can grant admin.
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
recipients: [
{
role: 'viewer',
user_id: 'usr_01h2xcejqtf2nbrexx3vqjhp41',
email: 'alice@example.com',
bot_id: 'bot_01h2xcejqtf2nbrexx3vqjhp41'
}
],
should_send_notification: true,
custom_message: '<string>'
})
};
fetch('https://api.factify.com/v1/documents/{document_id}/sharing', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"total": 2,
"successful": 1,
"failed": 1,
"results": [
{
"recipient": {
"role": "viewer",
"user_id": "usr_01h2xcejqtf2nbrexx3vqjhp41",
"email": "alice@example.com",
"bot_id": "bot_01h2xcejqtf2nbrexx3vqjhp41"
},
"success": true,
"error": "<string>"
}
]
}Documentation Index
Fetch the complete documentation index at: https://developers.factify.com/llms.txt
Use this file to discover all available pages before exploring further.
Authorizations
Bearer authentication using a factapi-issued API key
(ffy_<env>_<base32_uuid><base62_random>). Cookie-based
sessions are accepted automatically by user-facing endpoints
but are not surfaced as an OpenAPI auth scheme.
Path Parameters
Document ID
"doc_01h2xcejqtf2nbrexx3vqjhp41"
Body
Recipients to grant access to.
1 - 100 elementsShow child attributes
Show child attributes
Whether to email each recipient about the grant. Defaults to true. Set false to grant silently (test setup, bulk imports).
Optional message included in the share notification email.
Ignored when should_send_notification=false.
1000Response
OK — inspect results[].success per recipient.
Number of recipients in the request.
x >= 1Count of recipients granted access.
x >= 0Count of recipients that did not receive access.
x >= 0Per-recipient outcome, in the same order as the request.
Show child attributes
Show child attributes