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.

Parameters
  • id required
  • created required
  • name required
  • user_id required
  • parent_id required
  • system_folder required
  • shared required
  • total_documents required
  • documents required
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
    ID of the folder to get details of
  • filters=signing-status&filter-values optional
    Shows documents with specific status. Status filter values: signed, pending, waiting-for-me, waiting-for-others
  • filters=documents-created&filter-values optional
    Shows 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
    Shows documents that were updated starting from a specific date. Note: this filter is not applicable for Templates. Value format: Unix timestamp of the date
  • 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
  • limit optional
    Integer. 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
    Integer. Displays documents from specified position.
  • subfolder-data optional
    Defines whether sub-folders of the given folder are displayed in the response. Values: 1 - yes, displayed, 0 - no, don't show.
  • with_team_documents optional
    Boolean. Allows to display “Team Documents” folders. Allowed values: true, false.
  • include_documents_subfolders optional
    Boolean. Allows to hide subfolders and display all documents from those subfolders in the parent folder. Parameter works only for “Documents” and “Template” folder and their children. Default value: true
  • exclude_documents_relations optional
    Boolean. Allows to display short list of document info and increases maximum limit from 100 to 500 documents per page. Allowed values: true, false

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

More parameters
  • filters required
  • filter-values required
  • sortby required
  • order required
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" 
                
                  }