docusign_esign.apis.folders_api

  1# coding: utf-8
  2
  3"""
  4    DocuSign REST API
  5
  6    The DocuSign REST API provides you with a powerful, convenient, and simple Web services API for interacting with DocuSign.  # noqa: E501
  7
  8    OpenAPI spec version: v2.1
  9    Contact: devcenter@docusign.com
 10    Generated by: https://github.com/swagger-api/swagger-codegen.git
 11"""
 12
 13
 14from __future__ import absolute_import
 15
 16import sys
 17import os
 18import re
 19
 20# python 2 and python 3 compatibility library
 21from six import iteritems
 22
 23from ..client.configuration import Configuration
 24from ..client.api_client import ApiClient
 25
 26
 27class FoldersApi(object):
 28    """
 29    NOTE: This class is auto generated by the swagger code generator program.
 30    Do not edit the class manually.
 31    Ref: https://github.com/swagger-api/swagger-codegen
 32    """
 33
 34    def __init__(self, api_client=None):
 35        config = Configuration()
 36        if api_client:
 37            self.api_client = api_client
 38        else:
 39            if not config.api_client:
 40                config.api_client = ApiClient()
 41            self.api_client = config.api_client
 42
 43    def list(self, account_id, **kwargs):
 44        """
 45        Gets a list of the folders for the account.
 46        Retrieves a list of the folders for the account, including the folder hierarchy. You can specify whether to return just the template folder or template folder and normal folders by setting the `template` query string parameter.
 47        This method makes a synchronous HTTP request by default. To make an
 48        asynchronous HTTP request, please define a `callback` function
 49        to be invoked when receiving the response.
 50        >>> def callback_function(response):
 51        >>>     pprint(response)
 52        >>>
 53        >>> thread = api.list(account_id, callback=callback_function)
 54
 55        :param callback function: The callback function
 56            for asynchronous request. (optional)
 57        :param str account_id: The external account number (int) or account ID Guid. (required)
 58        :param str count:
 59        :param str include:
 60        :param str include_items:
 61        :param str start_position:
 62        :param str sub_folder_depth:
 63        :param str template: Specifies the items that are returned. Valid values are:   * include - The folder list will return normal folders plus template folders.  * only - Only the list of template folders are returned.
 64        :param str user_filter:
 65        :return: FoldersResponse
 66                 If the method is called asynchronously,
 67                 returns the request thread.
 68        """
 69        kwargs['_return_http_data_only'] = True
 70        if kwargs.get('callback'):
 71            return self.list_with_http_info(account_id, **kwargs)
 72        else:
 73            (data) = self.list_with_http_info(account_id, **kwargs)
 74            return data
 75
 76    def list_with_http_info(self, account_id, **kwargs):
 77        """
 78        Gets a list of the folders for the account.
 79        Retrieves a list of the folders for the account, including the folder hierarchy. You can specify whether to return just the template folder or template folder and normal folders by setting the `template` query string parameter.
 80        This method makes a synchronous HTTP request by default. To make an
 81        asynchronous HTTP request, please define a `callback` function
 82        to be invoked when receiving the response.
 83        >>> def callback_function(response):
 84        >>>     pprint(response)
 85        >>>
 86        >>> thread = api.list_with_http_info(account_id, callback=callback_function)
 87
 88        :param callback function: The callback function
 89            for asynchronous request. (optional)
 90        :param str account_id: The external account number (int) or account ID Guid. (required)
 91        :param str count:
 92        :param str include:
 93        :param str include_items:
 94        :param str start_position:
 95        :param str sub_folder_depth:
 96        :param str template: Specifies the items that are returned. Valid values are:   * include - The folder list will return normal folders plus template folders.  * only - Only the list of template folders are returned.
 97        :param str user_filter:
 98        :return: FoldersResponse
 99                 If the method is called asynchronously,
100                 returns the request thread.
101        """
102
103        all_params = ['account_id', 'count', 'include', 'include_items', 'start_position', 'sub_folder_depth', 'template', 'user_filter']
104        all_params.append('callback')
105        all_params.append('_return_http_data_only')
106        all_params.append('_preload_content')
107        all_params.append('_request_timeout')
108
109        params = locals()
110        for key, val in iteritems(params['kwargs']):
111            if key not in all_params:
112                raise TypeError(
113                    "Got an unexpected keyword argument '%s'"
114                    " to method list" % key
115                )
116            params[key] = val
117        del params['kwargs']
118        # verify the required parameter 'account_id' is set
119        if ('account_id' not in params) or (params['account_id'] is None):
120            raise ValueError("Missing the required parameter `account_id` when calling `list`")
121
122
123        collection_formats = {}
124
125        resource_path = '/v2.1/accounts/{accountId}/folders'.replace('{format}', 'json')
126        path_params = {}
127        if 'account_id' in params:
128            path_params['accountId'] = params['account_id']
129
130        query_params = {}
131        if 'count' in params:
132            query_params['count'] = params['count']
133        if 'include' in params:
134            query_params['include'] = params['include']
135        if 'include_items' in params:
136            query_params['include_items'] = params['include_items']
137        if 'start_position' in params:
138            query_params['start_position'] = params['start_position']
139        if 'sub_folder_depth' in params:
140            query_params['sub_folder_depth'] = params['sub_folder_depth']
141        if 'template' in params:
142            query_params['template'] = params['template']
143        if 'user_filter' in params:
144            query_params['user_filter'] = params['user_filter']
145
146        header_params = {}
147
148        form_params = []
149        local_var_files = {}
150
151        body_params = None
152        # HTTP header `Accept`
153        header_params['Accept'] = self.api_client.\
154            select_header_accept(['application/json'])
155
156        # Authentication setting
157        auth_settings = []
158
159        return self.api_client.call_api(resource_path, 'GET',
160                                        path_params,
161                                        query_params,
162                                        header_params,
163                                        body=body_params,
164                                        post_params=form_params,
165                                        files=local_var_files,
166                                        response_type='FoldersResponse',
167                                        auth_settings=auth_settings,
168                                        callback=params.get('callback'),
169                                        _return_http_data_only=params.get('_return_http_data_only'),
170                                        _preload_content=params.get('_preload_content', True),
171                                        _request_timeout=params.get('_request_timeout'),
172                                        collection_formats=collection_formats)
173
174    def list_items(self, account_id, folder_id, **kwargs):
175        """
176        Gets a list of the envelopes in the specified folder.
177        Retrieves a list of the envelopes in the specified folder. You can narrow the query by specifying search criteria in the query string parameters.
178        This method makes a synchronous HTTP request by default. To make an
179        asynchronous HTTP request, please define a `callback` function
180        to be invoked when receiving the response.
181        >>> def callback_function(response):
182        >>>     pprint(response)
183        >>>
184        >>> thread = api.list_items(account_id, folder_id, callback=callback_function)
185
186        :param callback function: The callback function
187            for asynchronous request. (optional)
188        :param str account_id: The external account number (int) or account ID Guid. (required)
189        :param str folder_id: The ID of the folder being accessed. (required)
190        :param str from_date:  Only return items on or after this date. If no value is provided, the default search is the previous 30 days. 
191        :param str include_items:
192        :param str owner_email:  The email of the folder owner. 
193        :param str owner_name:  The name of the folder owner. 
194        :param str search_text:  The search text used to search the items of the envelope. The search looks at recipient names and emails, envelope custom fields, sender name, and subject. 
195        :param str start_position: The position of the folder items to return. This is used for repeated calls, when the number of envelopes returned is too much for one return (calls return 100 envelopes at a time). The default value is 0.
196        :param str status: The current status of the envelope. If no value is provided, the default search is all/any status.
197        :param str to_date: Only return items up to this date. If no value is provided, the default search is to the current date.
198        :return: FolderItemsResponse
199                 If the method is called asynchronously,
200                 returns the request thread.
201        """
202        kwargs['_return_http_data_only'] = True
203        if kwargs.get('callback'):
204            return self.list_items_with_http_info(account_id, folder_id, **kwargs)
205        else:
206            (data) = self.list_items_with_http_info(account_id, folder_id, **kwargs)
207            return data
208
209    def list_items_with_http_info(self, account_id, folder_id, **kwargs):
210        """
211        Gets a list of the envelopes in the specified folder.
212        Retrieves a list of the envelopes in the specified folder. You can narrow the query by specifying search criteria in the query string parameters.
213        This method makes a synchronous HTTP request by default. To make an
214        asynchronous HTTP request, please define a `callback` function
215        to be invoked when receiving the response.
216        >>> def callback_function(response):
217        >>>     pprint(response)
218        >>>
219        >>> thread = api.list_items_with_http_info(account_id, folder_id, callback=callback_function)
220
221        :param callback function: The callback function
222            for asynchronous request. (optional)
223        :param str account_id: The external account number (int) or account ID Guid. (required)
224        :param str folder_id: The ID of the folder being accessed. (required)
225        :param str from_date:  Only return items on or after this date. If no value is provided, the default search is the previous 30 days. 
226        :param str include_items:
227        :param str owner_email:  The email of the folder owner. 
228        :param str owner_name:  The name of the folder owner. 
229        :param str search_text:  The search text used to search the items of the envelope. The search looks at recipient names and emails, envelope custom fields, sender name, and subject. 
230        :param str start_position: The position of the folder items to return. This is used for repeated calls, when the number of envelopes returned is too much for one return (calls return 100 envelopes at a time). The default value is 0.
231        :param str status: The current status of the envelope. If no value is provided, the default search is all/any status.
232        :param str to_date: Only return items up to this date. If no value is provided, the default search is to the current date.
233        :return: FolderItemsResponse
234                 If the method is called asynchronously,
235                 returns the request thread.
236        """
237
238        all_params = ['account_id', 'folder_id', 'from_date', 'include_items', 'owner_email', 'owner_name', 'search_text', 'start_position', 'status', 'to_date']
239        all_params.append('callback')
240        all_params.append('_return_http_data_only')
241        all_params.append('_preload_content')
242        all_params.append('_request_timeout')
243
244        params = locals()
245        for key, val in iteritems(params['kwargs']):
246            if key not in all_params:
247                raise TypeError(
248                    "Got an unexpected keyword argument '%s'"
249                    " to method list_items" % key
250                )
251            params[key] = val
252        del params['kwargs']
253        # verify the required parameter 'account_id' is set
254        if ('account_id' not in params) or (params['account_id'] is None):
255            raise ValueError("Missing the required parameter `account_id` when calling `list_items`")
256        # verify the required parameter 'folder_id' is set
257        if ('folder_id' not in params) or (params['folder_id'] is None):
258            raise ValueError("Missing the required parameter `folder_id` when calling `list_items`")
259
260
261        collection_formats = {}
262
263        resource_path = '/v2.1/accounts/{accountId}/folders/{folderId}'.replace('{format}', 'json')
264        path_params = {}
265        if 'account_id' in params:
266            path_params['accountId'] = params['account_id']
267        if 'folder_id' in params:
268            path_params['folderId'] = params['folder_id']
269
270        query_params = {}
271        if 'from_date' in params:
272            query_params['from_date'] = params['from_date']
273        if 'include_items' in params:
274            query_params['include_items'] = params['include_items']
275        if 'owner_email' in params:
276            query_params['owner_email'] = params['owner_email']
277        if 'owner_name' in params:
278            query_params['owner_name'] = params['owner_name']
279        if 'search_text' in params:
280            query_params['search_text'] = params['search_text']
281        if 'start_position' in params:
282            query_params['start_position'] = params['start_position']
283        if 'status' in params:
284            query_params['status'] = params['status']
285        if 'to_date' in params:
286            query_params['to_date'] = params['to_date']
287
288        header_params = {}
289
290        form_params = []
291        local_var_files = {}
292
293        body_params = None
294        # HTTP header `Accept`
295        header_params['Accept'] = self.api_client.\
296            select_header_accept(['application/json'])
297
298        # Authentication setting
299        auth_settings = []
300
301        return self.api_client.call_api(resource_path, 'GET',
302                                        path_params,
303                                        query_params,
304                                        header_params,
305                                        body=body_params,
306                                        post_params=form_params,
307                                        files=local_var_files,
308                                        response_type='FolderItemsResponse',
309                                        auth_settings=auth_settings,
310                                        callback=params.get('callback'),
311                                        _return_http_data_only=params.get('_return_http_data_only'),
312                                        _preload_content=params.get('_preload_content', True),
313                                        _request_timeout=params.get('_request_timeout'),
314                                        collection_formats=collection_formats)
315
316    def move_envelopes(self, account_id, folder_id, **kwargs):
317        """
318        Moves an envelope from its current folder to the specified folder.
319        Moves envelopes to the specified folder.
320        This method makes a synchronous HTTP request by default. To make an
321        asynchronous HTTP request, please define a `callback` function
322        to be invoked when receiving the response.
323        >>> def callback_function(response):
324        >>>     pprint(response)
325        >>>
326        >>> thread = api.move_envelopes(account_id, folder_id, callback=callback_function)
327
328        :param callback function: The callback function
329            for asynchronous request. (optional)
330        :param str account_id: The external account number (int) or account ID Guid. (required)
331        :param str folder_id: The ID of the folder being accessed. (required)
332        :param FoldersRequest folders_request:
333        :return: FoldersResponse
334                 If the method is called asynchronously,
335                 returns the request thread.
336        """
337        kwargs['_return_http_data_only'] = True
338        if kwargs.get('callback'):
339            return self.move_envelopes_with_http_info(account_id, folder_id, **kwargs)
340        else:
341            (data) = self.move_envelopes_with_http_info(account_id, folder_id, **kwargs)
342            return data
343
344    def move_envelopes_with_http_info(self, account_id, folder_id, **kwargs):
345        """
346        Moves an envelope from its current folder to the specified folder.
347        Moves envelopes to the specified folder.
348        This method makes a synchronous HTTP request by default. To make an
349        asynchronous HTTP request, please define a `callback` function
350        to be invoked when receiving the response.
351        >>> def callback_function(response):
352        >>>     pprint(response)
353        >>>
354        >>> thread = api.move_envelopes_with_http_info(account_id, folder_id, callback=callback_function)
355
356        :param callback function: The callback function
357            for asynchronous request. (optional)
358        :param str account_id: The external account number (int) or account ID Guid. (required)
359        :param str folder_id: The ID of the folder being accessed. (required)
360        :param FoldersRequest folders_request:
361        :return: FoldersResponse
362                 If the method is called asynchronously,
363                 returns the request thread.
364        """
365
366        all_params = ['account_id', 'folder_id', 'folders_request']
367        all_params.append('callback')
368        all_params.append('_return_http_data_only')
369        all_params.append('_preload_content')
370        all_params.append('_request_timeout')
371
372        params = locals()
373        for key, val in iteritems(params['kwargs']):
374            if key not in all_params:
375                raise TypeError(
376                    "Got an unexpected keyword argument '%s'"
377                    " to method move_envelopes" % key
378                )
379            params[key] = val
380        del params['kwargs']
381        # verify the required parameter 'account_id' is set
382        if ('account_id' not in params) or (params['account_id'] is None):
383            raise ValueError("Missing the required parameter `account_id` when calling `move_envelopes`")
384        # verify the required parameter 'folder_id' is set
385        if ('folder_id' not in params) or (params['folder_id'] is None):
386            raise ValueError("Missing the required parameter `folder_id` when calling `move_envelopes`")
387
388
389        collection_formats = {}
390
391        resource_path = '/v2.1/accounts/{accountId}/folders/{folderId}'.replace('{format}', 'json')
392        path_params = {}
393        if 'account_id' in params:
394            path_params['accountId'] = params['account_id']
395        if 'folder_id' in params:
396            path_params['folderId'] = params['folder_id']
397
398        query_params = {}
399
400        header_params = {}
401
402        form_params = []
403        local_var_files = {}
404
405        body_params = None
406        if 'folders_request' in params:
407            body_params = params['folders_request']
408        # HTTP header `Accept`
409        header_params['Accept'] = self.api_client.\
410            select_header_accept(['application/json'])
411
412        # Authentication setting
413        auth_settings = []
414
415        return self.api_client.call_api(resource_path, 'PUT',
416                                        path_params,
417                                        query_params,
418                                        header_params,
419                                        body=body_params,
420                                        post_params=form_params,
421                                        files=local_var_files,
422                                        response_type='FoldersResponse',
423                                        auth_settings=auth_settings,
424                                        callback=params.get('callback'),
425                                        _return_http_data_only=params.get('_return_http_data_only'),
426                                        _preload_content=params.get('_preload_content', True),
427                                        _request_timeout=params.get('_request_timeout'),
428                                        collection_formats=collection_formats)
429
430    def search(self, account_id, search_folder_id, **kwargs):
431        """
432        Gets a list of envelopes in folders matching the specified criteria.
433        Retrieves a list of envelopes that match the criteria specified in the query.  If the user ID of the user making the call is the same as the user ID for any returned recipient, then the userId property is added to the returned information for those recipients.
434        This method makes a synchronous HTTP request by default. To make an
435        asynchronous HTTP request, please define a `callback` function
436        to be invoked when receiving the response.
437        >>> def callback_function(response):
438        >>>     pprint(response)
439        >>>
440        >>> thread = api.search(account_id, search_folder_id, callback=callback_function)
441
442        :param callback function: The callback function
443            for asynchronous request. (optional)
444        :param str account_id: The external account number (int) or account ID Guid. (required)
445        :param str search_folder_id: Specifies the envelope group that is searched by the request. These are logical groupings, not actual folder names. Valid values are: drafts, awaiting_my_signature, completed, out_for_signature. (required)
446        :param str all: Specifies that all envelopes that match the criteria are returned.
447        :param str count: Specifies the number of records returned in the cache. The number must be greater than 0 and less than or equal to 100.
448        :param str from_date: Specifies the start of the date range to return. If no value is provided, the default search is the previous 30 days.
449        :param str include_recipients: When set to **true**, the recipient information is returned in the response.
450        :param str order: Specifies the order in which the list is returned. Valid values are: `asc` for ascending order, and `desc` for descending order.
451        :param str order_by: Specifies the property used to sort the list. Valid values are: `action_required`, `created`, `completed`, `sent`, `signer_list`, `status`, or `subject`.
452        :param str start_position: Specifies the the starting location in the result set of the items that are returned.
453        :param str to_date: Specifies the end of the date range to return.
454        :return: FolderItemResponse
455                 If the method is called asynchronously,
456                 returns the request thread.
457        """
458        kwargs['_return_http_data_only'] = True
459        if kwargs.get('callback'):
460            return self.search_with_http_info(account_id, search_folder_id, **kwargs)
461        else:
462            (data) = self.search_with_http_info(account_id, search_folder_id, **kwargs)
463            return data
464
465    def search_with_http_info(self, account_id, search_folder_id, **kwargs):
466        """
467        Gets a list of envelopes in folders matching the specified criteria.
468        Retrieves a list of envelopes that match the criteria specified in the query.  If the user ID of the user making the call is the same as the user ID for any returned recipient, then the userId property is added to the returned information for those recipients.
469        This method makes a synchronous HTTP request by default. To make an
470        asynchronous HTTP request, please define a `callback` function
471        to be invoked when receiving the response.
472        >>> def callback_function(response):
473        >>>     pprint(response)
474        >>>
475        >>> thread = api.search_with_http_info(account_id, search_folder_id, callback=callback_function)
476
477        :param callback function: The callback function
478            for asynchronous request. (optional)
479        :param str account_id: The external account number (int) or account ID Guid. (required)
480        :param str search_folder_id: Specifies the envelope group that is searched by the request. These are logical groupings, not actual folder names. Valid values are: drafts, awaiting_my_signature, completed, out_for_signature. (required)
481        :param str all: Specifies that all envelopes that match the criteria are returned.
482        :param str count: Specifies the number of records returned in the cache. The number must be greater than 0 and less than or equal to 100.
483        :param str from_date: Specifies the start of the date range to return. If no value is provided, the default search is the previous 30 days.
484        :param str include_recipients: When set to **true**, the recipient information is returned in the response.
485        :param str order: Specifies the order in which the list is returned. Valid values are: `asc` for ascending order, and `desc` for descending order.
486        :param str order_by: Specifies the property used to sort the list. Valid values are: `action_required`, `created`, `completed`, `sent`, `signer_list`, `status`, or `subject`.
487        :param str start_position: Specifies the the starting location in the result set of the items that are returned.
488        :param str to_date: Specifies the end of the date range to return.
489        :return: FolderItemResponse
490                 If the method is called asynchronously,
491                 returns the request thread.
492        """
493
494        all_params = ['account_id', 'search_folder_id', 'all', 'count', 'from_date', 'include_recipients', 'order', 'order_by', 'start_position', 'to_date']
495        all_params.append('callback')
496        all_params.append('_return_http_data_only')
497        all_params.append('_preload_content')
498        all_params.append('_request_timeout')
499
500        params = locals()
501        for key, val in iteritems(params['kwargs']):
502            if key not in all_params:
503                raise TypeError(
504                    "Got an unexpected keyword argument '%s'"
505                    " to method search" % key
506                )
507            params[key] = val
508        del params['kwargs']
509        # verify the required parameter 'account_id' is set
510        if ('account_id' not in params) or (params['account_id'] is None):
511            raise ValueError("Missing the required parameter `account_id` when calling `search`")
512        # verify the required parameter 'search_folder_id' is set
513        if ('search_folder_id' not in params) or (params['search_folder_id'] is None):
514            raise ValueError("Missing the required parameter `search_folder_id` when calling `search`")
515
516
517        collection_formats = {}
518
519        resource_path = '/v2.1/accounts/{accountId}/search_folders/{searchFolderId}'.replace('{format}', 'json')
520        path_params = {}
521        if 'account_id' in params:
522            path_params['accountId'] = params['account_id']
523        if 'search_folder_id' in params:
524            path_params['searchFolderId'] = params['search_folder_id']
525
526        query_params = {}
527        if 'all' in params:
528            query_params['all'] = params['all']
529        if 'count' in params:
530            query_params['count'] = params['count']
531        if 'from_date' in params:
532            query_params['from_date'] = params['from_date']
533        if 'include_recipients' in params:
534            query_params['include_recipients'] = params['include_recipients']
535        if 'order' in params:
536            query_params['order'] = params['order']
537        if 'order_by' in params:
538            query_params['order_by'] = params['order_by']
539        if 'start_position' in params:
540            query_params['start_position'] = params['start_position']
541        if 'to_date' in params:
542            query_params['to_date'] = params['to_date']
543
544        header_params = {}
545
546        form_params = []
547        local_var_files = {}
548
549        body_params = None
550        # HTTP header `Accept`
551        header_params['Accept'] = self.api_client.\
552            select_header_accept(['application/json'])
553
554        # Authentication setting
555        auth_settings = []
556
557        return self.api_client.call_api(resource_path, 'GET',
558                                        path_params,
559                                        query_params,
560                                        header_params,
561                                        body=body_params,
562                                        post_params=form_params,
563                                        files=local_var_files,
564                                        response_type='FolderItemResponse',
565                                        auth_settings=auth_settings,
566                                        callback=params.get('callback'),
567                                        _return_http_data_only=params.get('_return_http_data_only'),
568                                        _preload_content=params.get('_preload_content', True),
569                                        _request_timeout=params.get('_request_timeout'),
570                                        collection_formats=collection_formats)