Document State#
You can only send a document in the document.draft status.
After creating a new document, it usually retains a document.uploaded status for 3-5 seconds while the document syncs across Pigeon servers. When the document is available for further API calls, it moves to the document.draft state. Use Document Status or Webhooks to check document status.
Moving a document to the document.sent status finalizes the document structure, before recipients can complete it.
If a template used for the document creation has an approval workflow turned on, the sent document moves to the document.waiting_approval status. Once the document is approved, you need to make the call again to move the document to document.sent status.
Send and Silence Notifications#
By default, Pigeon sends a document.sent notification email to the recipient as well as any internal notifications the sender has opted for. This can be bypassed by passing silent: true. Using this will suppress sent, viewed, comment and completed document notifications. This is useful when you are using alternative delivery methods such as linking to the document or embedding the document.
The silent: true parameter disables sent, viewed, comment and completed document email notifications. "Document Approval" notification won't be affected by this parameter.
When opting to send an email, passing the optional message attribute will result in an email like the following. At this time, you cannot customize the email beyond the user avatar. If you wish to perform any additional customization, we recommend generating view session links and using your own email distribution methods.
Select Approver from Group#
If you have previously set up an approval workflow with selectable groups on the UI, you can select a particular approver from this group.Request
Body Params application/json
{
"message": "Hello! This document was sent from the Pigeon API",
"subject": "Please check this test API document from Pigeon",
"silent": true,
"sender": {
"membership_id": "QMDSzwabfFzTgjW6KijHyu",
"email": "john.doe@example.com"
},
"forwarding_settings": {
"forwarding_allowed": true,
"forwarding_with_reassigning_allowed": true
},
"selected_approvers": {
"steps": [
{
"id": "LzWmancTxrgfTMpsJP9Eqd",
"group": {
"id": "op9MA75HygJHiV4aeVHXCH",
"type": "selectable",
"assignees": [
{
"user": "tpBLrk3vJoLggypMSRt92i",
"is_selected": true
}
]
}
}
]
}
}
Request Code Samples
curl --location --request POST '/documents/ZPeAfcpzr9aiVs5vqUf6jg/send' \
--header 'Content-Type: application/json' \
--data-raw '{
"message": "Hello! This document was sent from the Pigeon API",
"subject": "Please check this test API document from Pigeon",
"silent": true,
"sender": {
"membership_id": "QMDSzwabfFzTgjW6KijHyu",
"email": "john.doe@example.com"
},
"forwarding_settings": {
"forwarding_allowed": true,
"forwarding_with_reassigning_allowed": true
},
"selected_approvers": {
"steps": [
{
"id": "LzWmancTxrgfTMpsJP9Eqd",
"group": {
"id": "op9MA75HygJHiV4aeVHXCH",
"type": "selectable",
"assignees": [
{
"user": "tpBLrk3vJoLggypMSRt92i",
"is_selected": true
}
]
}
}
]
}
}'
Responses
{
"id": "msFYActMfJHqNTKH8YSvF1",
"name": "API Sample Document from Pigeon Template",
"status": "document.sent",
"date_created": "2018-02-06T08:42:13.836022Z",
"date_modified": "2018-02-06T08:42:13.836022Z",
"expiration_date": "2018-02-06T08:42:13.836022Z",
"version": "2",
"uuid": "msFYActMfJHqNTKH8YSvF1",
"recipients": [
{
"id": "7kqXgjFejB2toXxjcC5jfZ",
"first_name": "Jhon",
"last_name": "Dow",
"recipient_type": "CC",
"email": "test@test.com",
"phone": "+14842634627",
"delivery_methods": {
"email": true,
"sms": false
},
"signing_order": "string",
"shared_link": "https://app.pigeondocuments.com/document/b7f11ea3c09d1c11208cc122457d4f3a2829d364"
}
]
}
Modified at 2024-09-18 01:45:26
