Folder

Folders serve for storing user’s documents. Folder endpoints allow you to create folders for users. By default, there are three folders in every account: “Documents”, “Templates”, and “Archive”. Subfolders can be created only for these three and their child folders.

The folder object

Attributes
  • id string
    Unique identifier of the folder.
  • created string
    Unix timestamp of when the folder was created.
  • name string
    The name of the folder.
  • user_id string
    Identifier for the folder owner.
  • parent_id string
    Identifier for the parent folder that contains this folder.
  • system_folder boolean
    Whether or not this is a system folder: true - yes, it is a system folder; false - no, it’s not a system folder.
  • shared boolean
    Whether or not this folder is shared: true - yes, it is a shared folder; false - no, it’s not a shared folder.
  • folders array[object]
    Child folders and their attributes.
  • total_documents integer
    How many documents in this folder.
  • documents array[object]
    Document objects stored in this folder and their attributes.
Example event subscription in response here:
                { 
              
                  "id": "1893180697eb9bc2965f5e1b5a502a0942718d04", 
              
                  "created": "1409253077", 
              
                  "name": "Documents", 
              
                  "user_id": "38b7eb73d859cd9f6a8695817635fa14d58d0fe3", 
              
                  "parent_id": "07813645c2052dd0f18ce23a798411fd16e64720", 
              
                  "system_folder": true, 
              
                  "shared": false, 
              
                  "folders": [], 
              
                  "total_documents": 1, 
              
                  "documents": [ 
              
                    { 
              
                      "id": "85fecd9634b6d653f73ee96e7312947c5836834d", 
              
                      "user_id": "38b7eb73d859cd9f6a8695817635fa14d58d0fe3", 
              
                      "document_name": "forfun", 
              
                      "page_count": "1", 
              
                      "created": "1413307342", 
              
                      "updated": "1413485018", 
              
                      "original_filename": "forfun.pdf", 
              
                      "origin_document_id": "4a97327d3c8a45d0d257d24dc6f020ef9208d854", 
              
                      "owner": "sophiahelp@mailinator.com", 
              
                      "origin_user_id": "38b7eb73d859cd9f6a8695817635fa14d58d0fe3", 
              
                      "thumbnail": 
              
                        { 
              
                          "small": "http:\/\/api.vm.signnow.com\/document\/85fecd9634b6d653f73ee96e7312947c5836834d\/thumbnail?size=small", 
              
                          "medium": "http:\/\/api.vm.signnow.com\/document\/85fecd9634b6d653f73ee96e7312947c5836834d\/thumbnail?size=medium", 
              
                          "large": "http:\/\/api.vm.signnow.com\/document\/85fecd9634b6d653f73ee96e7312947c5836834d\/thumbnail?size=large" 
              
                        }, 
              
                      "template": false, 
              
                      "signatures": [ 
              
                        { 
              
                          "id": "5cff77fd67f7620e5efa07a335f28f05480e91f5", 
              
                          "user_id": "ab33e0689cd3419f8f6e1200156d4c0105b0b961", 
              
                          "email": "user1@signnow.com", 
              
                          "page_number": "0", 
              
                          "width": "122",    
              
                          "height": "25", 
              
                          "x": "91", 
              
                          "y": "195", 
              
                          "created": "1413485018" 
              
                        } 
              
                      ], 
              
                      "seals": [], 
              
                      "texts": [ 
              
                        { 
              
                          "id": "d2c2aaf73875e537db25ad30191dd6fdfa8766c4", 
              
                          "user_id": "ab33e0689cd3419f8f6e1200156d4c0105b0b961", 
              
                          "page_number": "0", 
              
                          "email": "user1@signnow.com", 
              
                          "font": "Arial", 
              
                          "size": "8", 
              
                          "data": "10\/16\/14", 
              
                          "x": "281", 
              
                          "y": "195", 
              
                          "line_height": "9.08", 
              
                          "created": "1413485018" 
              
                        } 
              
                      ],
              
                      "checks": [], 
              
                      "inserts": [], 
              
                      "tags": [ 
              
                        { 
              
                          "type": "system", 
              
                          "name": "fields" 
              
                        } 
              
                      ], 
              
                      "fields": [ 
              
                        { 
              
                          "id": "ecbd4d8594c3c279ab77dc3d630f0a7865e13ec5", 
              
                          "type": "text", 
              
                          "role_id": "1025e1f678944126d55fa8244adb40dbfbe4eae5", 
              
                          "json_attributes": { 
              
                            "page_number": 0, 
              
                            "x": 281, 
              
                            "y": 195, 
              
                            "width": 102, 
              
                            "height": 21, 
              
                            "required": true, 
              
                            "label": "Date", 
              
                            "prefilled_text": "" 
              
                          }, 
              
                          "role": "Client", 
              
                          "originator": "user2@signnow.com", 
              
                          "fulfiller": "user1@signnow.com", 
              
                          "field_request_id": "40df08b6b97e5448795d666d945bac6feb7cfe47", 
              
                          "element_id": "d2c2aaf73875e537db25ad30191dd6fdfa8766c4", 
              
                          "field_request_canceled": null, 
              
                          "template_field_id": "726f1cd9b3777ffe19e087e509eb1777588bb36b", 
              
                          "field_id": "40df08b6b97e5448795d666d945bac6feb7cfe47" 
              
                        }, 
              
                        { 
              
                          "id": "43a434da73c0127beb49954869c94347a3af496e", 
              
                          "type": "signature", 
              
                          "role_id": "1025e1f678944126d55fa8244adb40dbfbe4eae5", 
              
                          "json_attributes": { 
              
                            "page_number": 0, 
              
                            "x": 91, 
              
                            "y": 186, 
              
                            "width": 122, 
              
                            "height": 34, 
              
                            "required": true 
              
                          }, 
              
                          "role": "Client", 
              
                          "originator": "user2@signnow.com", 
              
                          "fulfiller": "user1@signnow.com", 
              
                          "field_request_id": "4d766371aca992ec963dae1704a015cf5e8eb14f", 
              
                          "element_id": "5cff77fd67f7620e5efa07a335f28f05480e91f5", 
              
                          "field_request_canceled": null, 
              
                          "template_field_id": "e9536f562ec1edc27070ae097b2a40339a172645", 
              
                          "field_id": "4d766371aca992ec963dae1704a015cf5e8eb14f" 
              
                        } 
              
                      ], 
              
                      "requests": [], 
              
                      "notary_invites": [], 
              
                      "roles": [ 
              
                        { 
              
                          "unique_id": "1025e1f678944126d55fa8244adb40dbfbe4eae5", 
              
                          "signing_order": "1", 
              
                          "name": "Client" 
              
                        } 
              
                      ], 
              
                      "field_invites": [ 
              
                        { 
              
                          "id": "73f0a1f97afb21309f0248dbf460f24eea0bd36a", 
              
                          "status": "fulfilled", 
              
                          "updated": "1413485018", 
              
                          "email": "user1@signnow.com", 
              
                          "role": "Client" 
              
                        } 
              
                      ], 
              
                      "version_time": "1413485018", 
              
                      "enumeration_options": [], 
              
                      "attachments": [], 
              
                      "exported_to": [ 
              
                        {
              
                          "export_domain": "copy.com", 
              
                          "is_exported": false, 
              
                          "exported_user_ids": [] 
              
                        } 
              
                      ], 
              
                      "parent_id": "1893180697eb9bc2965f5e1b5a502a0942718d04" 
              
                    } 
              
                  ] 
              
                }
              

Create folder

Creates a folder for the user.

Parameters
  • name required
    Name of a new folder
  • parent_id required
    Identifier for the parent folder that contains this folder
Returns

Returns ID of a new folder.

POST /user/folder
                  
                    curl 
                    -X POST
                     \
                  
                
                  
                      https://api-eval.signnow.com/user/folder \
                     \
                  
                
                  
                      -H
                     'Authorization:
                     Bearer {{access_token}}'
                  
                
                  
                      -H
                     'Content-Type: 
                     application/json'
                     \
                  
                
                  
                      -d
                     '{
                  
                
                  
                       "name":
                     "Folder Name"
                  
                
                  
                       "parent_id":
                     "f02df1f8bd27f93e902748091047dd8d6b720760"
                  
                
                  
                    }'
                  
                
Response
                  {
                
                    "id": "98186eaa80e98eadb17bc8e5a9257b6095757395"
                
                  } 
                

Get all folders

Returns all folders of a user.

Returns

Returns all information about user’s folders.

GET /user/folder
                  
                    curl 
                    -X GET
                     \
                  
                
                  
                       https://api-eval.signnow.com/user/folder
                     \
                  
                
                  
                      -H
                     'Authorization:
                     Bearer {{access_token}}'
                  
                
Response
                    Response
                
                    { 
                
                    "id": "3864f8a9674a72644288549a5f6923e20ba1f4aa", 
                
                    "created": "1532531633", 
                
                    "name": "Root", 
                
                    "user_id": "890d13607d89a7b3f6e67a14757d02ec00cf5eae", 
                
                    "parent_id": null, 
                
                    "system_folder": false, 
                
                    "shared": false, 
                
                    "folders": [ 
                
                      { 
                
                        "id": "254681a17bd2f13e72af8de3a73170b6641f9d86", 
                
                        "user_id": "890d13607d89a7b3f6e67a14757d02ec00cf5eae", 
                
                        "name": "Templates", 
                
                        "created": "1532531633", 
                
                        "shared": false, 
                
                        "document_count": "0", 
                
                        "template_count": "11", 
                
                        "folder_count": "0", 
                
                        "sub_folders": [] 
                
                      }, 
                
                      { 
                
                        "id": "3b826587963d46b98d5b0b28d154c8732d9c5cfc", 
                
                        "user_id": "890d13607d89a7b3f6e67a14757d02ec00cf5eae", 
                
                        "name": "Team Templates", 
                
                        "created": "1557915422", 
                
                        "shared": true, 
                
                        "document_count": "0", 
                
                        "template_count": "3", 
                
                        "folder_count": "0", 
                
                        "sub_folders": [], 
                
                        "team_name": "Torchmark", 
                
                        "team_id": "c3f5f21ecb1c423193824a946beb43dd408cde32", 
                
                        "team_type": "VIEWABLE" 
                
                      }, 
                
                      { 
                
                        "id": "54128ae8bdb79fb21a970c92e6d780b9b6a973ac", 
                
                        "user_id": "890d13607d89a7b3f6e67a14757d02ec00cf5eae", 
                
                        "name": "Team Templates", 
                
                        "created": "1543922139", 
                
                        "shared": true, 
                
                        "document_count": "0", 
                
                        "template_count": "1", 
                
                        "folder_count": "0", 
                
                        "sub_folders": [], 
                
                        "team_name": "my team", 
                
                        "team_id": "960396a6d502e03743c7bd5da0e396bb61d582d2", 
                
                        "team_type": "VIEWABLE" 
                
                      }, 
                
                      { 
                
                        "id": "83dd89ffe463b1ac609b593ebf1edf1aa840127a", 
                
                        "user_id": "890d13607d89a7b3f6e67a14757d02ec00cf5eae", 
                
                        "name": "Archive", 
                
                        "created": "1532531633", 
                
                        "shared": false, 
                
                        "document_count": "21", 
                
                        "template_count": 0, 
                
                        "folder_count": "0", 
                
                        "sub_folders": [] 
                
                      }, 
                
                      { 
                
                        "id": "9e99b7a6c0b55a586474b67953a3a7cc0f7aed9d", 
                
                        "user_id": "890d13607d89a7b3f6e67a14757d02ec00cf5eae", 
                
                        "name": "Trash Bin", 
                
                        "created": "1567466970", 
                
                        "shared": false, 
                
                        "document_count": "0", 
                
                        "template_count": 0, 
                
                        "folder_count": "0", 
                
                        "sub_folders": [] 
                
                      }, 
                
                      { 
                
                        "id": "c8fdb570bddbefab469a30a8cb4de4d96851cce3", 
                
                        "user_id": "890d13607d89a7b3f6e67a14757d02ec00cf5eae", 
                
                        "name": "Documents", 
                
                        "created": "1532531633", 
                
                        "shared": false, 
                
                        "document_count": "74", 
                
                        "template_count": 0, 
                
                        "folder_count": "0", 
                
                        "sub_folders": [] 
                
                      } 
                
                    ], 
                
                  "total_documents": 0, 
                
                  "documents": [] 
                

Get folder by id

Returns all details of a specific folder including an array of all documents in that folder.

Parameters
  • folder_id required
    Path parameter: ID of the folder to get details of
  • entity_type=all/document/document-group optional
    Query parameter: a filter which returns the list of entities in the folder. Possible values: all - return all active documents and document groups in the folder, documents included in the document groups are not displayed; document - return the list of documents; document-group - return document groups only.
  • subfolder-data= optional
    Query parameter: a filter that returns all sub-folders of the given folder. Possible values: 1 - yes, show all subfolders, 0 - no, don't show.
  • with_team_documents= optional
    Query parameter. Allows to display “Team Documents” folders. Possible values: true, false.
  • exclude_documents_relations= optional
    Query parameter. Allows to display documents of the folder with a short list of document info and increases maximum limit to 500 documents per page. Default limit is 100 documents per page. Possible values: true, false

    A short list of document info includes: "id", "user_id", "document_name", "page_count", "created", "updated", "original_filename"

  • include_documents_subfolders= optional
    Query parameter. Allows to show/hide documents contained in the subfolders of a specific folder. Parameter works only for “Documents” and “Template” folders and their children. Possible values: true - show subfolders and the documents they contain; false - hide the documents, show only subfolders.
  • limit= optional
    Query parameter. Displays specified number of documents; Max limit is 100. It means that if value of “limit” parameter exceeds 100, response is automatically limited to 100 documents.
  • offset= optional
    Query parameter. Displays documents from specified position. Possible values: numbers
  • filters=signing-status&filter-values= optional
    Query parameter. Returns documents with specific status. Filter values: signed, pending, waiting-for-me, waiting-for-others, draft-exists
  • filters=documents-created&filter-values= optional
    Query parameter. Returns documents that were created starting from a specific date. Note: this filter is not applicable for Templates. Value format: Unix timestamp of the date
  • filters=documents-updated&filter-values= optional
    Query parameter. Returns documents that were updated starting from a specific date. Note: this filter is not applicable for Templates. Value format: Unix timestamp of the date
  • filters=has-fields&filter-values= optional
    Query parameter. Returns documents with fields and roles or without any. Possible values: 0 - return documents with no fields and roles; 1 - return documents with fields and roles.
  • filters=is-updated&filter-values= optional
    Query parameter. Allows users to filter documents which have or have not been updated. Possible values: 0 - return documents that have not been updated; 1 - return documents that have been updated.
  • filters=template&filter-values={{template_id}} optional
    Query parameter. Allows users to filter documents which have been created from a particular template.
  • sortby=created&order= optional
    Sorts documents by creation date in descending or ascending order. Possible values: desc, asc
  • sortby=updated&order= optional
    Sorts documents by update date in descending or ascending order. Possible values: desc, asc
  • sortby=document-name&order= optional
    Sorts documents by name in descending or ascending alphabetical order. Possible values: desc - from Z to A, asc - from A to Z.
Returns

Returns all details of a specific folder including an array of all documents in that folder.

GET /folder/{folder_id}
                  
                    curl 
                    -X GET
                     \
                  
                
                  
                       https://api-eval.signnow.com/folder/{{folder_id}}
                     \
                  
                
                  
                      -H
                     'Authorization:
                     Bearer {{access_token}}'
                  
                
Response
                    { 
                
                    "id": "1893180697eb9bc2965f5e1b5a502a0942718d04", 
                
                    "created": "1409253077", 
                
                    "name": "Documents", 
                
                    "user_id": "38b7eb73d859cd9f6a8695817635fa14d58d0fe3", 
                
                    "parent_id": "07813645c2052dd0f18ce23a798411fd16e64720", 
                
                    "system_folder": true, 
                
                    "shared": false, 
                
                    "folders": [], 
                
                    "total_documents": 1, 
                
                    "documents": [ 
                
                      { 
                
                        "id": "85fecd9634b6d653f73ee96e7312947c5836834d", 
                
                        "user_id": "38b7eb73d859cd9f6a8695817635fa14d58d0fe3", 
                
                        "document_name": "forfun", 
                
                        "page_count": "1", 
                
                        "created": "1413307342", 
                
                        "updated": "1413485018", 
                
                        "original_filename": "forfun.pdf", 
                
                        "origin_document_id": "4a97327d3c8a45d0d257d24dc6f020ef9208d854", 
                
                        "owner": "sophiahelp@mailinator.com", 
                
                        "origin_user_id": "38b7eb73d859cd9f6a8695817635fa14d58d0fe3", 
                
                        "thumbnail": 
                
                          { 
                
                            "small": "http:\/\/api.vm.signnow.com\/document\/85fecd9634b6d653f73ee96e7312947c5836834d\/thumbnail?size=small", 
                
                            "medium": "http:\/\/api.vm.signnow.com\/document\/85fecd9634b6d653f73ee96e7312947c5836834d\/thumbnail?size=medium", 
                
                            "large": "http:\/\/api.vm.signnow.com\/document\/85fecd9634b6d653f73ee96e7312947c5836834d\/thumbnail?size=large" 
                
                          }, 
                
                        "template": false, 
                
                        "signatures": [ 
                
                          { 
                
                            "id": "5cff77fd67f7620e5efa07a335f28f05480e91f5", 
                
                            "user_id": "ab33e0689cd3419f8f6e1200156d4c0105b0b961", 
                
                            "email": "user1@signnow.com", 
                
                            "page_number": "0", 
                
                            "width": "122",    
                
                            "height": "25", 
                
                            "x": "91", 
                
                            "y": "195", 
                
                            "created": "1413485018" 
                
                          } 
                
                        ], 
                
                        "seals": [], 
                
                        "texts": [ 
                
                          { 
                
                            "id": "d2c2aaf73875e537db25ad30191dd6fdfa8766c4", 
                
                            "user_id": "ab33e0689cd3419f8f6e1200156d4c0105b0b961", 
                
                            "page_number": "0", 
                
                            "email": "user1@signnow.com", 
                
                            "font": "Arial", 
                
                            "size": "8", 
                
                            "data": "10\/16\/14", 
                
                            "x": "281", 
                
                            "y": "195", 
                
                            "line_height": "9.08", 
                
                            "created": "1413485018" 
                
                          } 
                
                        ],
                
                        "checks": [], 
                
                        "inserts": [], 
                
                        "tags": [ 
                
                          { 
                
                            "type": "system", 
                
                            "name": "fields" 
                
                          } 
                
                        ], 
                
                        "fields": [ 
                
                          { 
                
                            "id": "ecbd4d8594c3c279ab77dc3d630f0a7865e13ec5", 
                
                            "type": "text", 
                
                            "role_id": "1025e1f678944126d55fa8244adb40dbfbe4eae5", 
                
                            "json_attributes": { 
                
                              "page_number": 0, 
                
                              "x": 281, 
                
                              "y": 195, 
                
                              "width": 102, 
                
                              "height": 21, 
                
                              "required": true, 
                
                              "label": "Date", 
                
                              "prefilled_text": "" 
                
                            }, 
                
                            "role": "Client", 
                
                            "originator": "user2@signnow.com", 
                
                            "fulfiller": "user1@signnow.com", 
                
                            "field_request_id": "40df08b6b97e5448795d666d945bac6feb7cfe47", 
                
                            "element_id": "d2c2aaf73875e537db25ad30191dd6fdfa8766c4", 
                
                            "field_request_canceled": null, 
                
                            "template_field_id": "726f1cd9b3777ffe19e087e509eb1777588bb36b", 
                
                            "field_id": "40df08b6b97e5448795d666d945bac6feb7cfe47" 
                
                          }, 
                
                          { 
                
                            "id": "43a434da73c0127beb49954869c94347a3af496e", 
                
                            "type": "signature", 
                
                            "role_id": "1025e1f678944126d55fa8244adb40dbfbe4eae5", 
                
                            "json_attributes": { 
                
                              "page_number": 0, 
                
                              "x": 91, 
                
                              "y": 186, 
                
                              "width": 122, 
                
                              "height": 34, 
                
                              "required": true 
                
                            }, 
                
                            "role": "Client", 
                
                            "originator": "user2@signnow.com", 
                
                            "fulfiller": "user1@signnow.com", 
                
                            "field_request_id": "4d766371aca992ec963dae1704a015cf5e8eb14f", 
                
                            "element_id": "5cff77fd67f7620e5efa07a335f28f05480e91f5", 
                
                            "field_request_canceled": null, 
                
                            "template_field_id": "e9536f562ec1edc27070ae097b2a40339a172645", 
                
                            "field_id": "4d766371aca992ec963dae1704a015cf5e8eb14f" 
                
                          } 
                
                        ], 
                
                        "requests": [], 
                
                        "notary_invites": [], 
                
                        "roles": [ 
                
                          { 
                
                            "unique_id": "1025e1f678944126d55fa8244adb40dbfbe4eae5", 
                
                            "signing_order": "1", 
                
                            "name": "Client" 
                
                          } 
                
                        ], 
                
                        "field_invites": [ 
                
                          { 
                
                            "id": "73f0a1f97afb21309f0248dbf460f24eea0bd36a", 
                
                            "status": "fulfilled", 
                
                            "updated": "1413485018", 
                
                            "email": "user1@signnow.com", 
                
                            "role": "Client" 
                
                          } 
                
                        ], 
                
                        "version_time": "1413485018", 
                
                        "enumeration_options": [], 
                
                        "attachments": [], 
                
                        "exported_to": [ 
                
                          {
                
                            "export_domain": "copy.com", 
                
                            "is_exported": false, 
                
                            "exported_user_ids": [] 
                
                          } 
                
                        ], 
                
                        "parent_id": "1893180697eb9bc2965f5e1b5a502a0942718d04" 
                
                      } 
                
                    ] 
                
                  }
                

Delete folder

Deletes a folder.

Parameters
  • folder_id required
    ID of the folder to delete
Returns

Returns the deletion status.

DELETE /user/folder/{folder_id}
                  
                    curl 
                    -X DELETE
                     \
                  
                
                  
                       https://api-eval.signnow.com/folder/folder_id
                     \
                  
                
                  
                      -H
                     'Authorization:
                     Bearer {{access_token}}'
                  
                
Response
                  { 
                
                    "success": true 
                
                  }
                

Rename folder

Renames a folder.

Parameters
  • folder_id required
    ID of the folder to rename
  • name required
    A new folder’s name
Returns

Returns ID of the renamed folder.

PUT /user/folder/{folder_id}
                  
                    curl 
                    -X PUT
                     \
                  
                
                  
                       https://api-eval.signnow.com/user/folder/{{folder_id}}
                     \
                  
                
                  
                      -H
                     'Authorization:
                     Bearer {{access_token}}'
                  
                
                  
                      -H
                     'Content-Type: 
                     application/json'
                     \
                  
                
                  
                      -d
                     '{
                  
                
                  
                       "name":
                     "new folder name"
                  
                
                  
                    }
                  
                
Response
                  { 
                
                    "id": "98186eaa80e98eadb17bc8e5a9257b6095757395" 
                
                  }