--- title: "Get document group info (v.2)" method: GET path: "/v2/document-groups/{document_group_id}" --- # Get document group info (v.2) `GET /v2/document-groups/{document_group_id}` ## Request - Base URL: `https://api.signnow.com` - URL: `https://api.signnow.com/v2/document-groups/{document_group_id}` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) This endpoint allows API users to retrieve detailed information about a specific document group, including its documents, assigned roles, field and FreeForm invites, share info, owner details, and originator organization settings. Available to the document group owner and to any user invited on any step, regardless of the current invite or step status. **Notes** * Use the `include` query parameter to add optional data to the response. To request several values, separate them with commas, for example `?include=documents.fields,reminder`. Unknown values are ignored. * With `?include=documents.fields`, each item in `documents` contains a `fields` array. Without it, the response doesn't include `fields`, so existing integrations are not affected. * The objects in `fields` have the same format as the `fields` array of [`GET /document/{document_id}`](/docs/document/operations/get-document) and cover all field types it returns. * The response doesn't include dropdown options (`enumeration_options`) or checkbox groups (`checkbox_groups`). [`GET /document/{document_id}`](/docs/document/operations/get-document) returns them at the document level, so call it for each document that needs them. * To add or update fields, call [`PUT /document/{document_id}`](/docs/document/operations/edit-document) for each document. ## Response `200` Successful response. Returns the document group with its documents, invites, and owner. To also return document fields, signatures, labels, the source template, or the last activity time, use the `include` query parameter. - object - `data` object: Document group details. - `id` string: Unique identifier of the document group. - `name` string: Display name of the document group. - `owner` object: Information about the document group owner, including organization details. - `id` string: ID of the owner. - `email` string: Email address of the owner. - `organization` object: Organization the owner belongs to. - `id` string: ID of the organization. `null` if the owner is not in an organization. - `state` 'created' | 'pending' | 'canceled' | 'completed' | 'declined' | 'correction': Current state of the document group. Possible values: `created` — the document group has been created; `pending` — an invite has been sent and is awaiting signing; `canceled` — the document group invite was canceled; `completed` — all signing steps are completed; `declined` — one of the signers declined to sign; `correction` — the document group is in correction mode. - `created` integer: Unix timestamp when the document group was created. - `updated` integer: Unix timestamp of the last update to the document group. - `cc_emails` string[]: List of email addresses to be CC'd on invite emails. - `documents` object[]: List of documents in the document group. - `id` string: ID of the document. - `owner` object: Owner of the document. - `id` string: ID of the owner. - `email` string: Email address of the owner. - `roles` string[]: Roles assigned in the document. Empty if the document has no roles. - `fields` object[]: Fields in the document. Returned only with `?include=documents.fields`. An empty array if the document has no fields. Each object has the same format as an item of the `fields` array returned by [`GET /document/{document_id}`](/docs/document/operations/get-document). - `id` string: Unique identifier of the field. - `role` string: Name of the role the field is assigned to. - `type` 'text' | 'signature' | 'checkbox' | 'initials' | 'enumeration' | 'attachment' | 'radiobutton' | 'hyperlink' | 'stamp': Field type. - `radio` object[]: For `radiobutton` fields only: the buttons in the radio group. - `x` integer: Horizontal position of the button, in pixels. - `y` integer: Vertical position of the button, in pixels. - `value` string: Value of the button. - `width` integer: Width of the button, in pixels. - `height` integer: Height of the button, in pixels. - `checked` integer: `1` if the button is selected, `0` otherwise. - `created` integer: Unix timestamp when the button was created. - `radio_id` string: Unique identifier of the radio button. - `page_number` integer: Zero-based number of the page the button is on. - `json_attributes` unknown[]: Additional button attributes. Empty array if none. - unknown - `role_id` string: Unique identifier of the role the field is assigned to. Role IDs are unique per document: a role with the same name has a different `role_id` in each document of the group. To match roles across documents, use `role`. - `field_id` string: Same value as `field_request_id`. Kept for compatibility with `GET /document/{document_id}`. - `fulfiller` string: Email address of the recipient the field is assigned to through an invite. `null` if no invite has been sent for the field. - `element_id` string: Unique identifier of the value the recipient entered in the field. `null` until the field is filled in. - `originator` string: Email address of the document owner. - `json_attributes` object: Position, size, and settings of the field. The set of keys depends on the field type. - `x` integer: Horizontal position of the field on the page, in pixels. - `y` integer: Vertical position of the field on the page, in pixels. - `bold` boolean: `true` if the text is bold. - `font` string: Font name, for example `Arial`. - `name` string: Name of the field. - `size` number: Font size in the SignNow editor scale, where the page is rendered `890` pixels wide. From `8` to `72`. - `align` 'left' | 'center' | 'right': Horizontal text alignment. - `color` string: Text color as a 6-character hex code without `#`, for example `000000`. - `label` string: Label of the field shown to the recipient. Returned only if a label is set. - `value` string: For `checkbox` fields: the checkbox label. - `width` integer: Width of the field, in pixels. - `height` integer: Height of the field, in pixels. - `italic` boolean: `true` if the text is italic. - `valign` 'top' | 'middle' | 'bottom': Vertical text alignment. - `required` boolean: `true` if the recipient must fill in the field. - `font_size` number: Font size on the document page, in PDF points. The same size as `size`, converted to the page scale. - `max_chars` integer: Maximum number of characters the recipient can enter. From `0` to `999`; `0` means no limit. - `max_lines` integer: Maximum number of lines the recipient can enter. From `0` to `99`; `0` means no limit. - `underline` boolean: `true` if the text is underlined. - `arrangement` 'none' | 'cells': How the text is laid out in the field. `none`: regular text. `cells`: one character per cell; `max_lines` is then `1`. - `page_number` integer: Zero-based number of the page the field is on. - `allowed_types` string[]: For `signature` fields: the ways the recipient can add a signature. Possible values: `type`, `draw`, `upload`. - `prefilled_text` string: For `checkbox` fields: `"0"` if the checkbox is not checked by default. For `text` fields: the prefilled value, if set. - `custom_defined_option` string: For `enumeration` (dropdown) fields: whether the recipient can enter their own value instead of choosing a listed option. An empty string or `false` means they can't. - `field_request_id` string: Unique identifier of the field request created when the invite was sent. If the field has several field requests, the fulfilled one is returned, otherwise the one for the requesting user or the first one. `null` if no invite has been sent for the field. - `template_field_id` string: Unique identifier of the template field this field was created from. `null` if the field was not created from a template. - `field_request_canceled` string: Always `null`. Kept for compatibility with `GET /document/{document_id}`. - `updated` integer: Unix timestamp of the last update of the document. - `settings` object[]: Settings of the document. - `folder_id` string: ID of the folder that contains the document. - `thumbnail` object: Thumbnail URLs of the first page of the document. - `large` string: URL of the large thumbnail. - `small` string: URL of the small thumbnail. - `medium` string: URL of the medium thumbnail. - `has_fields` boolean: `true` if the document has fillable fields. - `page_count` integer: Number of pages in the document. - `signatures` object[]: Signatures added to the document. Returned only with `?include=documents.signatures`. - `id` string: Unique identifier of the signature. - `created` string: Unix timestamp when the signature was added, as a string. - `user_id` string: Unique identifier of the user who added the signature. - `document_name` string: Name of the document. - `field_invites` object[]: Field invites sent for the document. - `id` string: ID of the field invite. - `role` string: Name of the recipient role. - `action` string: Action the recipient must perform: `sign`, `view`, or `approve`. - `status` string: Status of the invite, for example `pending`, `fulfilled`, or `declined`. - `created` integer: Unix timestamp of when the invite was created. - `message` string: Message of the invite email. - `updated` integer: Unix timestamp of the last update of the invite. - `language` string: Language of the signing session and notification emails: `en`, `es`, or `fr`. `null` if not set. - `compliance` object: Compliance settings of the invite. - `cfr` string: 21 CFR Part 11 settings of the invite. `null` if not applied. - `email_group` object: Email group the invite was sent to. `id` and `name` are `null` if the invite was sent to a single recipient. - `id` string: ID of the email group. `null` if the invite was sent to a single recipient. - `name` string: Name of the email group. `null` if the invite was sent to a single recipient. - `signer_email` string: Email address of the recipient. - `signing_order` integer: Position of the recipient in the signing order. - `email_statuses` object[]: List of email delivery events recorded for this invite. Each object represents one event. The array is empty (`[]`) if no email events have been recorded yet. - `status` 'sent' | 'mail_open' | 'bounce' | 'mail_click' | 'reminder_sent' | 'undefined': Email delivery event status. Possible values: `sent` — email was successfully sent to the recipient; `mail_open` — email was opened by the recipient; `bounce` — email bounced, delivery failed (e.g. invalid address); `mail_click` — a link in the email was clicked by the recipient; `reminder_sent` — a reminder email was sent to the recipient; `undefined` — the event status is unknown. - `created_at` integer: Unix timestamp when the event was recorded. - `last_reaction_at` integer: Unix timestamp of the last status update. - `short_link_url` string: Short link to the invite. `null` if not generated. - `signature_type` string: Type of signature required from the signer. `null` if not set. - `expiration_days` integer: Number of days before the invite expires. - `expiration_time` integer: Unix timestamp of when the invite expires. - `payment_request` string: Payment request attached to the invite. `null` if there is none. - `is_full_declined` boolean: `true` if the recipient declined the invite. - `next_reminder_at` integer: Unix timestamp of the next reminder. `null` if no reminder is scheduled. - `sms_sent_statuses` object[]: SMS delivery events of the invite. Empty for email invites. - `password_protected` string: `"1"` if the invite is password-protected, otherwise `"0"`. - `signer_phone_invite` string: Phone number the SMS invite was sent to. `null` for email invites. - `allow_to_remove` boolean: `true` if the document can be removed from the document group. - `freeform_invites` object[]: FreeForm invites sent for the document. Returned only with `?include=documents.freeform_invites`. Canceled invites are not returned. - `id` string: Unique identifier of the FreeForm invite (signature request). - `email` string: Email address of the recipient. - `status` string: Status of the invite, for example `pending` or `fulfilled`. - `language` string: Language of the invite email, for example `en`. `null` if not set. - `email_statuses` object[]: List of email delivery events recorded for this FreeForm invite. Each object represents one event. The array is empty (`[]`) if no email events have been recorded yet. - `status` 'sent' | 'mail_open' | 'bounce' | 'mail_click' | 'undefined': Email delivery event status for this FreeForm invite. Possible values: `sent` — email was successfully sent to the recipient; `mail_open` — email was opened by the recipient; `bounce` — email bounced, delivery failed (e.g. invalid address); `mail_click` — a link in the email was clicked by the recipient; `undefined` — the event status is unknown. - `created_at` integer: Unix timestamp when the event was recorded. - `last_reaction_at` integer: Unix timestamp of the last status update. - `shared_with_team` string: ID of the team the document is shared with. `null` if not shared. - `origin_document_id` string: ID of the source document if this document was created as a copy. `null` otherwise. - `has_unassigned_field` boolean: `true` if the document has fields not assigned to any role. - `has_credit_card_number` boolean: `true` if the document has a credit card number field. - `folder_id` string: Unique identifier of the folder that contains the document group, or `null` if the group is not in a folder. - `invite_id` string: Unique identifier of the active group invite, or `null` if no invite has been created. - `expires_at` integer: Unix timestamp (Unix time, seconds) of the soonest expiration among pending field invites, including embedded invites, while the document group is in the `pending` or `correction` state. Unlike `general_expiration_time`, it is returned without `?include=reminder`. `null` for FreeForm invites, for document groups in the `completed`, `canceled`, or `declined` state, and when no pending invite has an expiration time yet, for example an embedded invite before its signing link is generated. - `origin_dgt` object: Document group template the document group was created from. Returned only with `?include=origin_dgt`. `null` if the group was not created from a template. - `id` string: Unique identifier of the document group template. - `owner_id` string: Unique identifier of the template owner. - `template_group_name` string: Name of the document group template. - `share_info` object: Sharing information for the document group, including team-level and personal sharing flags and the requesting user's role. - `role` string: Access level of the current user: `owner`, `sender`, or `viewer`. - `is_team_shared` boolean: `true` if the item is shared with a team. - `workspace_role` string: Role of the current user in the workspace. `null` if not applicable. - `is_personally_shared_to_others` boolean: `true` if the current user shared the item with other users. - `owner_email` string: Email address of the document group owner. - `sender_name` string: Display name of the user who sent the most recent invite for this document group. - `completed_at` integer: Unix timestamp (Unix time, seconds) when the document group reached the `completed` state. `null` in any other state. - `sender_email` string: Email address of the user who sent the most recent invite for this document group. - `entity_labels` object[]: Active labels assigned to the document group, for example when an invite email can't be delivered or a recipient declines to sign. Returned only with `?include=entity_labels`. An empty array if the group has no labels. - `updated` integer: Unix timestamp (seconds) when the label was last updated. - `is_system` boolean: `true` if SignNow assigned the label automatically. - `label_name` string: Name of the label, for example `undelivered` or `declined`. - `mail_provider` string: Mail provider used for sending invite emails. `null` if the default provider is used. - `recently_used` integer: Unix timestamp of the last activity on the document group in the owner's folder. If not available, the same value as `updated`. Returned only with `?include=recently_used`. - `last_invite_id` string: Unique identifier of the most recent invite sent for this document group. - `sign_as_merged` boolean: `true` if the documents in the group are signed as a single merged document; `false` if signed individually. - `freeform_invite` object: Information about the FreeForm invite associated with this document group. The `id`, `last_id`, and `message` are `null` if no FreeForm invite has been created. - `id` string: ID of the FreeForm invite. `null` if no FreeForm invite was sent. - `last_id` string: ID of the last FreeForm invite. `null` if no FreeForm invite was sent. - `message` string: Message of the FreeForm invite email. `null` if not set. - `pending_step_id` string: Unique identifier of the current pending step in the signing flow, or `null` if no step is pending. - `general_reminder` object: Default `reminder` applied to all recipients in the invite. Returned only with `?include=reminder`. - `remind_after` integer: Days after invite is sent before a reminder is delivered. - `remind_before` integer: Days before expiration when a reminder is delivered. - `remind_repeat` integer: Days between repeated reminders. - `scheduled_invite` string: Information about a scheduled invite for the document group, or `null` if no invite is scheduled. - `general_expiration_days` integer: Default `expiration_days` applied to all recipients in the invite. Returned only with `?include=reminder`. - `general_expiration_time` integer: Default expiration timestamp (Unix time, seconds) applied to all recipients in the invite. Returned only with `?include=reminder`. - `email_action_on_complete` string: Specifies how documents are emailed when the document group invite is completed. `null` if no action is configured. - `document_group_attributes` object: Custom attributes for the document group, such as the sender email and sender name used for invites. - `from_name` string: Sender name shown in the subject of the invite, reassign, reminder, and completed emails of the document group. - `from_email` string: Sender email address shown in the invite, reassign, reminder, and completed emails of the document group. - `originator_organization_settings` object[]: Organization-level settings inherited from the document group owner's organization. - `value` string: Value of the setting, as a string. - `setting` string: Name of the setting. ## Other responses - `400`: * Wrong, expired, or missing token. - `403`: - Request with token that belongs to a user who is not the document group owner, was not invited to the group, and has no shared access to it. - `404`: - id does not exist. - id is not active. --- [API](https://skmtc.dev/signnow/apis/signnow-api.md) - [All operations](https://skmtc.dev/signnow/apis/signnow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signnow/apis/signnow-api/revisions/1c9c30a6142b?raw)