--- title: "Create scheduled invite" url: "https://docs.signnow.com/docs/scheduled-doc-group-invite/operations/post-document-group-scheduled-invite" type: "endpoint" section: "scheduled-doc-group-invite" slug: "scheduled-doc-group-invite/operations/post-document-group-scheduled-invite" method: "POST" path: "/documentgroup/{document_group_id}/scheduled-invite" operation_id: "post-document-group-scheduled-invite" authorization: "bearer" --- # Create scheduled invite `POST /documentgroup/{document_group_id}/scheduled-invite` This endpoint allows API users to create a scheduled document group invite. At the moment specified by `scheduled_timestamp`, the invite is sent to recipients automatically. Both freeform invite and field invite can be sent. **Notes** * A paid API plan or Site License is required to create a scheduled invite. * `scheduled_timestamp` must be a Unix timestamp (in seconds) that points to a moment in the future. * The invite type is detected from the `invite_data` payload shape: * If the documents in the group do **not** contain fields, pass a [freeform invite payload](/docs/doc-group-freeform-invite/operations/post-v2-document-groups-document_group_id-free-form-invites) in `invite_data`. * If the documents in the group contain fields, pass a [field invite payload](/docs/doc-group-field-invite/operations/invite-to-sign-document-group) in `invite_data`. * Each document group can have only one scheduled invite in the `active` status. ## Authorization bearer ## Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `document_group_id` | string | Yes | ID of the document group for which the scheduled invite is created. | ## Request Body **Schema** ```json { "type": "object", "required": [ "scheduled_timestamp", "invite_data" ], "properties": { "invite_data": { "type": "object", "description": "The full document group invite payload. The invite type is detected from the payload shape:\n\n* Send the same body as the [Create freeform document group invite](/docs/doc-group-freeform-invite/operations/post-v2-document-groups-document_group_id-free-form-invites) endpoint when the documents in the group do not contain fields.\n* Send the same body as the [Create field invite](/docs/doc-group-field-invite/operations/invite-to-sign-document-group) endpoint when the documents in the group contain fields." }, "scheduled_timestamp": { "type": "integer", "example": 1820000000, "description": "Unix timestamp (in seconds) of the moment when the prepared invite must be sent. Must be a positive integer that points to a moment in the future." } }, "x-examples": { "Field invite (document group with fields)": { "invite_data": { "cc": [ "cc-recipient@email.com" ], "order_type": "recipient_order", "invite_steps": [ { "order": 1, "invite_emails": [ { "email": "approver@email.com", "message": "Review and approve before sending to the signer.", "subject": "Please approve the document", "expiration_days": 30 } ], "invite_actions": [ { "email": "approver@email.com", "action": "approve", "role_name": "Approver", "document_id": "30XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "redirect_uri": "https://example.com/", "authentication": { "type": "phone", "phone": "+12025550123", "method": "phone_call" }, "redirect_target": "blank" } ] }, { "order": 2, "invite_emails": [ { "email": "signer1@email.com", "message": "Hi, please sign this document group.", "subject": "Please sign", "reminder": { "remind_after": 5, "remind_before": 3, "remind_repeat": 2 }, "expiration_days": 30 } ], "invite_actions": [ { "email": "signer1@email.com", "action": "sign", "role_name": "Signer 1", "document_id": "30XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "redirect_uri": "https://example.com/", "allow_reassign": "0", "authentication": { "type": "password", "value": "123456" }, "redirect_target": "blank", "decline_by_signature": "0", "decline_redirect_uri": "https://example.com/" } ] }, { "order": 3, "invite_emails": [ { "email": "viewer@email.com", "message": "The document has been signed. You can view it.", "subject": "Signed document" } ], "invite_actions": [ { "email": "viewer@email.com", "action": "view", "role_name": "Viewer", "document_id": "30XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" } ] } ], "sign_as_merged": false }, "scheduled_timestamp": 1820000000 }, "Freeform invite (document group without fields)": { "invite_data": { "cc": [ { "email": "cc-recipient@email.com" } ], "to": [ { "email": "signer1@email.com", "language": "en", "redirect_uri": "https://example.com/", "redirect_target": "blank" } ], "message": "Please sign this document group.", "subject": "Please sign this document group", "redirect_uri": "https://example.com/", "client_timestamp": 1820000000 }, "scheduled_timestamp": 1820000000 } } } ``` **Example** (`Field invite (document group with fields)`) ```json { "invite_data": { "cc": [ "cc-recipient@email.com" ], "order_type": "recipient_order", "invite_steps": [ { "order": 1, "invite_emails": [ { "email": "approver@email.com", "message": "Review and approve before sending to the signer.", "subject": "Please approve the document", "expiration_days": 30 } ], "invite_actions": [ { "email": "approver@email.com", "action": "approve", "role_name": "Approver", "document_id": "30XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "redirect_uri": "https://example.com/", "authentication": { "type": "phone", "phone": "+12025550123", "method": "phone_call" }, "redirect_target": "blank" } ] }, { "order": 2, "invite_emails": [ { "email": "signer1@email.com", "message": "Hi, please sign this document group.", "subject": "Please sign", "reminder": { "remind_after": 5, "remind_before": 3, "remind_repeat": 2 }, "expiration_days": 30 } ], "invite_actions": [ { "email": "signer1@email.com", "action": "sign", "role_name": "Signer 1", "document_id": "30XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "redirect_uri": "https://example.com/", "allow_reassign": "0", "authentication": { "type": "password", "value": "123456" }, "redirect_target": "blank", "decline_by_signature": "0", "decline_redirect_uri": "https://example.com/" } ] }, { "order": 3, "invite_emails": [ { "email": "viewer@email.com", "message": "The document has been signed. You can view it.", "subject": "Signed document" } ], "invite_actions": [ { "email": "viewer@email.com", "action": "view", "role_name": "Viewer", "document_id": "30XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" } ] } ], "sign_as_merged": false }, "scheduled_timestamp": 1820000000 } ``` **Example** (`Freeform invite (document group without fields)`) ```json { "invite_data": { "cc": [ { "email": "cc-recipient@email.com" } ], "to": [ { "email": "signer1@email.com", "language": "en", "redirect_uri": "https://example.com/", "redirect_target": "blank" } ], "message": "Please sign this document group.", "subject": "Please sign this document group", "redirect_uri": "https://example.com/", "client_timestamp": 1820000000 }, "scheduled_timestamp": 1820000000 } ``` ## Responses ### 204 Returned when the scheduled invite passes validation and is stored with the `active` status. The response body is empty. ### 400 Validation errors for the scheduled invite payload: * `scheduled_timestamp` is missing, null, not an integer, or points to a moment in the past. * `invite_data` is missing, null, of the wrong type, or empty. * The document group already has an active scheduled invite. * The document group already has an active group invite. * The user is not the document group owner. In addition, all validation errors that apply to the regular invite payload also apply to the contents of `invite_data`. **Example** (`invite_data is null`) ```json { "errors": [ { "code": 65536, "message": "The `invite_data` value should not be null." } ] } ``` **Example** (`invite_data is empty`) ```json { "errors": [ { "code": 65536, "message": "The `invite_data` value must not be an empty array." } ] } ``` **Example** (`invite_data wrong type`) ```json { "errors": [ { "code": 65536, "message": "The `invite_data` value should be of type array." } ] } ``` **Example** (`Incorrect scheduled time`) ```json { "errors": [ { "code": 65582, "message": "Incorrect scheduled time for invite." } ] } ``` **Example** (`Group invite already exists`) ```json { "errors": [ { "code": 65582, "message": "An invite already exists for this document group." } ] } ``` **Example** (`scheduled_timestamp is null`) ```json { "errors": [ { "code": 65536, "message": "The `scheduled_timestamp` value should not be null." } ] } ``` **Example** (`scheduled_timestamp wrong type`) ```json { "errors": [ { "code": 65536, "message": "The `scheduled_timestamp` value should be of type int." } ] } ``` **Example** (`Scheduled invite already exists`) ```json { "errors": [ { "code": 65582, "message": "A scheduled invite already exists." } ] } ``` **Example** (`User is not document group owner`) ```json { "errors": [ { "code": 65582, "message": "User is not document group owner" } ] } ``` ## Code Examples > Replace `$SIGNNOW_ACCESS_TOKEN` and any `{placeholder}` values before running. ### cURL ```bash curl -X POST \ "https://api.signnow.com/documentgroup/{document_group_id}/scheduled-invite" \ -H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{"invite_data": {"cc": ["cc-recipient@email.com"], "order_type": "recipient_order", "invite_steps": [{"order": 1, "invite_emails": [{"email": "approver@email.com", "message": "Review and approve before sending to the signer.", "subject": "Please approve the document", "expiration_days": 30}], "invite_actions": [{"email": "approver@email.com", "action": "approve", "role_name": "Approver", "document_id": "30XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "redirect_uri": "https://example.com/", "authentication": {"type": "phone", "phone": "+12025550123", "method": "phone_call"}, "redirect_target": "blank"}]}, {"order": 2, "invite_emails": [{"email": "signer1@email.com", "message": "Hi, please sign this document group.", "subject": "Please sign", "reminder": {"remind_after": 5, "remind_before": 3, "remind_repeat": 2}, "expiration_days": 30}], "invite_actions": [{"email": "signer1@email.com", "action": "sign", "role_name": "Signer 1", "document_id": "30XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "redirect_uri": "https://example.com/", "allow_reassign": "0", "authentication": {"type": "password", "value": "123456"}, "redirect_target": "blank", "decline_by_signature": "0", "decline_redirect_uri": "https://example.com/"}]}, {"order": 3, "invite_emails": [{"email": "viewer@email.com", "message": "The document has been signed. You can view it.", "subject": "Signed document"}], "invite_actions": [{"email": "viewer@email.com", "action": "view", "role_name": "Viewer", "document_id": "30XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"}]}], "sign_as_merged": false}, "scheduled_timestamp": 1820000000}' ``` --- *Full reference: https://docs.signnow.com/docs/scheduled-doc-group-invite/operations/post-document-group-scheduled-invite*